diff --git a/docs/ja-JP/cli/plugins.md b/docs/ja-JP/cli/plugins.md index b401c9580..4ae4e041f 100644 --- a/docs/ja-JP/cli/plugins.md +++ b/docs/ja-JP/cli/plugins.md @@ -1,28 +1,28 @@ --- read_when: - - GatewayのPluginまたは互換バンドルをインストールまたは管理したい場合 - - Pluginの読み込み失敗をデバッグしたい場合 + - Gatewayプラグインまたは互換バンドルをインストールまたは管理したい場合 + - プラグインの読み込み失敗をデバッグしたい場合 summary: '`openclaw plugins` のCLIリファレンス（list、install、marketplace、uninstall、enable/disable、doctor）' -title: Plugins +title: プラグイン x-i18n: - generated_at: "2026-04-24T04:51:32Z" + generated_at: "2026-04-24T15:21:29Z" model: gpt-5.4 provider: openai - source_hash: 35ef8f54c64ea52d7618a0ef8b90d3d75841a27ae4cd689b4ca8e0cfdcddc408 + source_hash: bc693d5e3bc49057e1a108ba65a4dcb3bb662c00229e6fa38a0335afba8240e5 source_path: cli/plugins.md workflow: 15 --- # `openclaw plugins` -GatewayのPlugin、フックパック、互換バンドルを管理します。 +Gatewayプラグイン、フックパック、および互換バンドルを管理します。 -関連: +関連項目: -- Pluginシステム: [Plugins](/ja-JP/tools/plugin) -- バンドル互換性: [Plugin bundles](/ja-JP/plugins/bundles) -- Plugin manifest + schema: [Plugin manifest](/ja-JP/plugins/manifest) -- セキュリティ強化: [Security](/ja-JP/gateway/security) +- Pluginシステム: [プラグイン](/ja-JP/tools/plugin) +- バンドル互換性: [Pluginバンドル](/ja-JP/plugins/bundles) +- Pluginマニフェスト + スキーマ: [Pluginマニフェスト](/ja-JP/plugins/manifest) +- セキュリティ強化: [セキュリティ](/ja-JP/gateway/security) ## コマンド @@ -46,118 +46,77 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -同梱PluginはOpenClawに含まれています。デフォルトで有効なものもあります（たとえば -同梱モデルプロバイダー、同梱音声プロバイダー、同梱browser -plugin）。それ以外は `plugins enable` が必要です。 +バンドル済みPluginはOpenClawに同梱されています。いくつかはデフォルトで有効です（たとえば、バンドル済みのモデルプロバイダー、バンドル済みの音声プロバイダー、バンドル済みのブラウザPlugin）。それ以外は `plugins enable` が必要です。 -ネイティブOpenClaw Pluginは、インラインJSON -Schema（空でも `configSchema` が必要）を含む `openclaw.plugin.json` を提供する必要があります。 -互換バンドルは代わりに独自のバンドルmanifestを使用します。 +ネイティブOpenClaw Pluginは、インラインJSON Schema（空の場合でも `configSchema`）を含む `openclaw.plugin.json` を含める必要があります。互換バンドルは代わりに独自のバンドルマニフェストを使用します。 -`plugins list` には `Format: openclaw` または `Format: bundle` が表示されます。詳細なlist/info -出力では、bundle subtype（`codex`、`claude`、または `cursor`）と、検出されたbundle -capabilitiesも表示されます。 +`plugins list` は `Format: openclaw` または `Format: bundle` を表示します。詳細なlist/info出力では、バンドルのサブタイプ（`codex`、`claude`、または `cursor`）に加えて、検出されたバンドル機能も表示されます。 ### インストール ```bash -openclaw plugins install # まずClawHub、その後npm +openclaw plugins install # まずClawHub、次にnpm openclaw plugins install clawhub: # ClawHubのみ openclaw plugins install --force # 既存のインストールを上書き openclaw plugins install --pin # バージョンを固定 openclaw plugins install --dangerously-force-unsafe-install openclaw plugins install # ローカルパス -openclaw plugins install @ # marketplace -openclaw plugins install --marketplace # marketplace（明示指定） +openclaw plugins install @ # マーケットプレイス +openclaw plugins install --marketplace # マーケットプレイス（明示指定） openclaw plugins install --marketplace https://github.com// ``` -プレーンなパッケージ名は、まずClawHub、次にnpmで確認されます。セキュリティ上の注意: -Pluginのインストールはコード実行と同等に扱ってください。バージョン固定を推奨します。 +素のパッケージ名は、まずClawHub、次にnpmで確認されます。セキュリティ上の注意: Pluginのインストールはコードの実行と同様に扱ってください。固定バージョンを推奨します。 -`plugins` セクションが単一ファイルの `$include` で管理されている場合、 -`plugins install/update/enable/disable/uninstall` はそのinclude先ファイルに書き込み、 -`openclaw.json` には触れません。ルートinclude、include配列、および兄弟override付きincludeは、 -フラット化せずフェイルクローズします。サポートされる形については [Config includes](/ja-JP/gateway/configuration) を参照してください。 +`plugins` セクションが単一ファイルの `$include` で構成されている場合、`plugins install/update/enable/disable/uninstall` はそのインクルード先ファイルに書き込み、`openclaw.json` は変更しません。ルートインクルード、インクルード配列、兄弟オーバーライドを持つインクルードは、フラット化せずにフェイルクローズします。対応する形状については [Config includes](/ja-JP/gateway/configuration) を参照してください。 -configが不正な場合、`plugins install` は通常フェイルクローズし、 -まず `openclaw doctor --fix` を実行するよう案内します。唯一の文書化された例外は、 -明示的に -`openclaw.install.allowInvalidConfigRecovery` -へオプトインしているPlugin向けの、限定的な同梱Plugin復旧パスです。 +設定が無効な場合、`plugins install` は通常フェイルクローズし、まず `openclaw doctor --fix` を実行するよう案内します。文書化されている唯一の例外は、`openclaw.install.allowInvalidConfigRecovery` に明示的にオプトインしたPlugin向けの、限定的なバンドル済みPlugin復旧パスです。 -`--force` は既存のインストール先を再利用し、すでにインストール済みの -Pluginまたはフックパックをその場で上書きします。新しいローカルパス、archive、ClawHubパッケージ、またはnpm artifactから、 -同じidを意図的に再インストールするときに使ってください。 -すでに追跡されているnpm Pluginの通常の更新には、 -`openclaw plugins update ` を推奨します。 +`--force` は既存のインストール先を再利用し、すでにインストール済みのPluginまたはフックパックをその場で上書きします。同じidを新しいローカルパス、アーカイブ、ClawHubパッケージ、またはnpmアーティファクトから意図的に再インストールする場合に使用します。すでに追跡されているnpm Pluginを通常アップグレードするには、`openclaw plugins update ` を使ってください。 -すでにインストール済みのplugin idに対して `plugins install` を実行すると、OpenClawは -停止し、通常の更新には `plugins update `、 -本当に別ソースから現在のインストールを上書きしたい場合は -`plugins install --force` を案内します。 +すでにインストール済みのPlugin idに対して `plugins install` を実行すると、OpenClawは停止し、通常のアップグレードには `plugins update ` を、本当に別ソースから現在のインストールを上書きしたい場合には `plugins install --force` を案内します。 -`--pin` はnpmインストール専用です。`--marketplace` とは併用できません。 -marketplaceインストールはnpm specではなくmarketplaceソースメタデータを保存するためです。 +`--pin` はnpmインストールにのみ適用されます。マーケットプレイスのインストールはnpm specではなくマーケットプレイスのソースメタデータを保持するため、`--marketplace` とは併用できません。 -`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーでの誤検知に対する -緊急用オプションです。組み込みスキャナーが `critical` findings を報告しても -インストールを継続できますが、pluginの `before_install` フックによるポリシーブロックや、 -scan failureは**回避しません**。 +`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる誤検知に対する最終手段のオプションです。組み込みスキャナーが `critical` の検出結果を報告してもインストールを続行できますが、Pluginの `before_install` フックポリシーによるブロックは回避できず、スキャン失敗も回避できません。 -このCLIフラグはplugin install/updateフローに適用されます。GatewayバックドのSkills -依存関係インストールでは対応する `dangerouslyForceUnsafeInstall` リクエスト -overrideを使います。一方、`openclaw skills install` は別のClawHub Skill -ダウンロード/インストールフローです。 +このCLIフラグはPluginのinstall/updateフローに適用されます。Gateway経由のSkills依存関係インストールでは対応する `dangerouslyForceUnsafeInstall` リクエストオーバーライドを使用します。一方で、`openclaw skills install` は別個のClawHub Skillsダウンロード/インストールフローのままです。 -`plugins install` は、`package.json` で `openclaw.hooks` を公開するフックパックの -インストール面でもあります。フィルタ済みのフック表示やフックごとの有効化には -パッケージインストールではなく `openclaw hooks` を使ってください。 +`plugins install` は、`package.json` に `openclaw.hooks` を公開するフックパックのインストール面でもあります。フィルタされたフック可視性やフックごとの有効化には `openclaw hooks` を使い、パッケージのインストールには使わないでください。 -npm specは**レジストリ専用**です（パッケージ名 + 任意の**厳密なバージョン**または -**dist-tag**）。Git/URL/file specおよびsemver rangeは拒否されます。依存関係の -インストールは安全のため `--ignore-scripts` 付きで実行されます。 +npm spec は**レジストリ専用**です（パッケージ名 + 任意の**正確なバージョン**または**dist-tag**）。Git/URL/file specやsemver rangeは拒否されます。安全のため、依存関係のインストールは `--ignore-scripts` 付きで実行されます。 -プレーンspecと `@latest` はstableトラックに留まります。npmがそのいずれかをprereleaseに解決した場合、 -OpenClawは停止し、`@beta`/`@rc` のようなprerelease tag、または -`@1.2.3-beta.4` のような厳密なprerelease versionで明示的にオプトインするよう求めます。 +素のspecと `@latest` は安定版トラックのままです。npmがそのいずれかをプレリリースに解決した場合、OpenClawは停止し、`@beta`/`@rc` のようなプレリリースタグ、または `@1.2.3-beta.4` のような正確なプレリリースバージョンで明示的にオプトインするよう求めます。 -プレーンなインストールspecが同梱plugin id（たとえば `diffs`）と一致する場合、OpenClawは -同梱pluginを直接インストールします。同名のnpmパッケージをインストールしたい場合は、 -明示的なscoped spec（たとえば `@scope/diffs`）を使ってください。 +素のインストールspecがバンドル済みPlugin id（たとえば `diffs`）と一致する場合、OpenClawはそのバンドル済みPluginを直接インストールします。同名のnpmパッケージをインストールするには、明示的なスコープ付きspec（たとえば `@scope/diffs`）を使用してください。 -サポートされるarchive: `.zip`, `.tgz`, `.tar.gz`, `.tar`。 +サポートされるアーカイブ: `.zip`、`.tgz`、`.tar.gz`、`.tar`。 -Claude marketplaceインストールもサポートされています。 +Claudeマーケットプレイスからのインストールにも対応しています。 -ClawHubインストールでは明示的な `clawhub:` locatorを使います: +ClawHubインストールでは、明示的な `clawhub:` ロケーターを使用します: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClawは現在、プレーンなnpm安全plugin specに対してもClawHubを優先します。 -ClawHubにそのパッケージまたはバージョンがない場合にのみnpmへフォールバックします: +OpenClawは現在、npmで安全な素のPlugin specに対してもClawHubを優先します。ClawHubにそのパッケージまたはバージョンがない場合にのみnpmへフォールバックします: ```bash openclaw plugins install openclaw-codex-app-server ``` -OpenClawはClawHubからパッケージarchiveをダウンロードし、通知された -plugin API / 最小gateway互換性を確認してから、通常の -archiveパス経由でインストールします。記録されたインストールには、後の更新のためにClawHub -ソースメタデータが保持されます。 +OpenClawはClawHubからパッケージアーカイブをダウンロードし、告知されたplugin API / 最小gateway互換性を確認したうえで、通常のアーカイブ経路でインストールします。記録されたインストールには、後の更新のためにClawHubのソースメタデータが保持されます。 -marketplace名がClaudeのローカルレジストリキャッシュ `~/.claude/plugins/known_marketplaces.json` に存在する場合は、 -`plugin@marketplace` 省略記法を使用します: +Claudeのローカルレジストリキャッシュ `~/.claude/plugins/known_marketplaces.json` にマーケットプレイス名が存在する場合は、`plugin@marketplace` の短縮記法を使用します: ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -marketplaceソースを明示的に渡したい場合は `--marketplace` を使います: +マーケットプレイスのソースを明示的に渡したい場合は `--marketplace` を使用します: ```bash openclaw plugins install --marketplace @@ -166,35 +125,26 @@ openclaw plugins install --marketplace https://github.com// openclaw plugins install --marketplace ./my-marketplace ``` -marketplaceソースには次のものを使用できます: +マーケットプレイスのソースには次のものを指定できます: -- `~/.claude/plugins/known_marketplaces.json` にあるClaude known-marketplace名 -- ローカルのmarketplaceルートまたは `marketplace.json` パス -- `owner/repo` のようなGitHubリポジトリ省略記法 +- `~/.claude/plugins/known_marketplaces.json` にあるClaude既知マーケットプレイス名 +- ローカルのマーケットプレイスルート、または `marketplace.json` のパス +- `owner/repo` のようなGitHubリポジトリ短縮表記 - `https://github.com/owner/repo` のようなGitHubリポジトリURL - git URL -GitHubまたはgitから読み込まれたリモートmarketplaceでは、pluginエントリは -クローンされたmarketplaceリポジトリ内に留まる必要があります。OpenClawは、その -リポジトリからの相対パスsourceは受け入れますが、リモートmanifestからのHTTP(S)、絶対パス、git、GitHub、 -その他の非パスplugin sourceは拒否します。 +GitHubまたはgitから読み込まれたリモートマーケットプレイスでは、Pluginエントリはクローンされたマーケットプレイスリポジトリ内にとどまる必要があります。OpenClawはそのリポジトリからの相対パスソースを受け入れ、リモートマニフェスト内のHTTP(S)、絶対パス、git、GitHub、およびその他の非パスPluginソースを拒否します。 -ローカルパスとarchiveでは、OpenClawは次を自動検出します: +ローカルパスとアーカイブについては、OpenClawが次を自動検出します: - ネイティブOpenClaw Plugin（`openclaw.plugin.json`） - Codex互換バンドル（`.codex-plugin/plugin.json`） -- Claude互換バンドル（`.claude-plugin/plugin.json` またはデフォルトのClaude - component layout） +- Claude互換バンドル（`.claude-plugin/plugin.json` またはデフォルトのClaudeコンポーネントレイアウト） - Cursor互換バンドル（`.cursor-plugin/plugin.json`） -互換バンドルは通常のpluginルートにインストールされ、同じ -list/info/enable/disableフローに参加します。現在のところ、bundle Skills、Claude -command-skills、Claude `settings.json` デフォルト、Claude `.lsp.json` / -manifest宣言の `lspServers` デフォルト、Cursor command-skills、および互換 -Codexフックディレクトリがサポートされています。その他の検出されたbundle capabilitiesは -診断/infoには表示されますが、まだランタイム実行には接続されていません。 +互換バンドルは通常のPluginルートにインストールされ、同じlist/info/enable/disableフローに参加します。現在は、バンドルのSkills、Claude command-skills、Claude `settings.json` のデフォルト、Claude `.lsp.json` / マニフェスト宣言の `lspServers` デフォルト、Cursor command-skills、および互換Codexフックディレクトリがサポートされています。その他の検出されたバンドル機能はdiagnostics/infoに表示されますが、まだランタイム実行には接続されていません。 -### 一覧表示 +### 一覧 ```bash openclaw plugins list @@ -203,22 +153,25 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -読み込まれているPluginだけを表示するには `--enabled` を使います。`--verbose` を使うと、 -テーブル表示から、source/origin/version/activation -メタデータ付きのPluginごとの詳細行表示に切り替わります。`--json` は機械可読なインベントリとregistry -診断を出力します。 +`--enabled` を使うと、読み込まれたPluginのみを表示します。`--verbose` を使うと、テーブル表示から、ソース/由来/バージョン/アクティベーションメタデータを含むPluginごとの詳細行に切り替わります。機械可読なインベントリとレジストリdiagnosticsには `--json` を使用します。 -ローカルディレクトリをコピーせずに使うには `--link` を使用します（`plugins.load.paths` に追加）: +`plugins list` は、現在のCLI環境と設定から検出を実行します。Pluginが有効か、読み込み可能かを確認するのには便利ですが、すでに実行中のGatewayプロセスに対するライブなランタイムプローブではありません。Pluginコード、有効化状態、フックポリシー、または `plugins.load.paths` を変更した後は、新しい `register(api)` コードやフックが実行されることを期待する前に、そのチャネルを提供しているGatewayを再起動してください。リモート/コンテナデプロイでは、ラッパープロセスだけでなく、実際の `openclaw gateway run` 子プロセスを再起動していることを確認してください。 + +ランタイムフックのデバッグ用: + +- `openclaw plugins inspect --json` は、モジュール読み込み済みのinspectionパスから、登録されたフックとdiagnosticsを表示します。 +- `openclaw gateway status --deep --require-rpc` は、到達可能なGateway、サービス/プロセスのヒント、configパス、RPCの健全性を確認します。 +- バンドルされていない会話フック（`llm_input`、`llm_output`、`agent_end`）には `plugins.entries..hooks.allowConversationAccess=true` が必要です。 + +ローカルディレクトリをコピーせずに使うには `--link` を使用します（`plugins.load.paths` に追加されます）: ```bash openclaw plugins install -l ./my-plugin ``` -リンクインストールは管理されたインストール先にコピーせず、source pathを再利用するため、 -`--link` と `--force` は併用できません。 +リンクインストールでは管理対象のインストール先へコピーせずソースパスを再利用するため、`--force` は `--link` と併用できません。 -npmインストールで `--pin` を使うと、デフォルト動作は非固定のままにしつつ、解決された厳密spec（`name@version`）を -`plugins.installs` に保存できます。 +npmインストールで `--pin` を使用すると、デフォルト動作を固定しないまま、解決された正確なspec（`name@version`）が `plugins.installs` に保存されます。 ### アンインストール @@ -228,13 +181,9 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` は `plugins.entries`、`plugins.installs`、 -plugin allowlist、および適用される場合はリンクされた `plugins.load.paths` -エントリからpluginレコードを削除します。アクティブなメモリPluginについては、memory slotは `memory-core` にリセットされます。 +`uninstall` は、`plugins.entries`、`plugins.installs`、Plugin許可リスト、および該当する場合はリンクされた `plugins.load.paths` エントリからPluginレコードを削除します。Active Memory Pluginの場合、メモリスロットは `memory-core` にリセットされます。 -デフォルトでは、アンインストールはアクティブな -state-dir pluginルート下のpluginインストールディレクトリも削除します。ディスク上のファイルを残したい場合は -`--keep-files` を使ってください。 +デフォルトでは、アンインストール時にアクティブなstate-dirのPluginルート配下にあるPluginインストールディレクトリも削除されます。ディスク上のファイルを残すには `--keep-files` を使用してください。 `--keep-config` は `--keep-files` の非推奨エイリアスとしてサポートされています。 @@ -248,37 +197,19 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -更新は `plugins.installs` の追跡対象インストールと、`hooks.internal.installs` の追跡対象フックパック -インストールに適用されます。 +更新は、`plugins.installs` 内の追跡対象インストールと、`hooks.internal.installs` 内の追跡対象フックパックインストールに適用されます。 -plugin idを渡すと、OpenClawはその -pluginに記録されたインストールspecを再利用します。つまり、以前保存された `@beta` のようなdist-tagや -厳密に固定されたバージョンは、後の `update ` 実行でも引き続き使われます。 +Plugin idを渡すと、OpenClawはそのPluginに記録されているインストールspecを再利用します。つまり、以前保存された `@beta` のようなdist-tagや、正確に固定されたバージョンは、その後の `update ` 実行でも引き続き使用されます。 -npmインストールでは、dist-tag -または厳密バージョン付きの明示的なnpm package specを渡すこともできます。OpenClawはそのパッケージ名を追跡対象plugin -レコードへ解決し、そのインストール済みpluginを更新して、将来の -idベース更新のために新しいnpm specを記録します。 +npmインストールでは、dist-tagまたは正確なバージョンを含む明示的なnpmパッケージspecを渡すこともできます。OpenClawはそのパッケージ名を追跡対象Pluginレコードに解決し、そのインストール済みPluginを更新し、今後のidベース更新のために新しいnpm specを記録します。 -バージョンやtagなしでnpm package名を渡しても、追跡対象plugin -レコードへ解決されます。pluginが厳密バージョンに固定されていて、 -レジストリのデフォルトリリースラインへ戻したい場合に使ってください。 +バージョンやタグなしでnpmパッケージ名を渡した場合も、追跡対象Pluginレコードに解決されます。これは、Pluginが正確なバージョンに固定されていて、それをレジストリのデフォルトリリース系列に戻したい場合に使用します。 -ライブのnpm更新前に、OpenClawはインストール済みパッケージのバージョンを -npmレジストリメタデータと照合します。インストール済みバージョンと記録済みartifact -identityが、解決された対象とすでに一致している場合、更新は -ダウンロード、再インストール、`openclaw.json` の書き換えを行わずにスキップされます。 +ライブのnpm更新の前に、OpenClawはインストール済みパッケージのバージョンをnpmレジストリメタデータと照合します。インストール済みバージョンと記録済みアーティファクト識別子が、解決された対象とすでに一致している場合、更新はスキップされ、ダウンロード、再インストール、`openclaw.json` の書き換えは行われません。 -保存済みintegrity hashが存在し、取得したartifact hashが変化している場合、 -OpenClawはそれをnpm artifact driftとして扱います。対話式の -`openclaw plugins update` コマンドは期待値と実際のhashを表示し、 -続行前に確認を求めます。非対話の更新ヘルパーは、呼び出し元が明示的な継続ポリシーを -指定しない限りフェイルクローズします。 +保存済みのintegrityハッシュが存在し、取得したアーティファクトのハッシュが変化した場合、OpenClawはそれをnpmアーティファクトドリフトとして扱います。対話型の `openclaw plugins update` コマンドは、想定されたハッシュと実際のハッシュを表示し、続行前に確認を求めます。非対話型の更新ヘルパーは、呼び出し側が明示的な続行ポリシーを指定しない限り、フェイルクローズします。 -`--dangerously-force-unsafe-install` は `plugins update` でも、 -plugin更新中の組み込み危険コードスキャン誤検知に対する緊急用overrideとして利用できます。 -それでもpluginの `before_install` ポリシーブロックや -scan-failureブロックは回避せず、hook-pack更新ではなくplugin更新にのみ適用されます。 +`--dangerously-force-unsafe-install` は、Plugin更新中に組み込みの危険コードスキャンで誤検知が起きた場合の最終手段オーバーライドとして、`plugins update` でも利用できます。これは依然としてPluginの `before_install` ポリシーブロックやスキャン失敗によるブロックを回避せず、Plugin更新にのみ適用され、フックパック更新には適用されません。 ### Inspect @@ -287,24 +218,20 @@ openclaw plugins inspect openclaw plugins inspect --json ``` -単一pluginの詳細な内観表示です。identity、読み込み状態、source、 -登録済みcapabilities、フック、ツール、コマンド、サービス、gateway methods、 -HTTP routes、ポリシーフラグ、診断、インストールメタデータ、bundle capabilities、 -および検出されたMCPまたはLSP serverサポートを表示します。 +単一Pluginの詳細なイントロスペクションです。ID、読み込み状態、ソース、登録された機能、フック、ツール、コマンド、サービス、Gatewayメソッド、HTTPルート、ポリシーフラグ、diagnostics、インストールメタデータ、バンドル機能、検出されたMCPまたはLSPサーバー対応を表示します。 -各pluginは、ランタイムで実際に何を登録したかによって分類されます: +各Pluginは、実行時に実際に登録する内容によって分類されます: -- **plain-capability** — 1種類のcapabilityタイプのみ（例: provider専用plugin） -- **hybrid-capability** — 複数のcapabilityタイプ（例: text + speech + images） -- **hook-only** — フックのみで、capabilitiesやsurfaceはなし -- **non-capability** — capabilitiesはないがtools/commands/servicesはある +- **plain-capability** — 1種類の機能タイプ（例: プロバイダー専用Plugin） +- **hybrid-capability** — 複数の機能タイプ（例: テキスト + 音声 + 画像） +- **hook-only** — フックのみで、機能やサーフェスなし +- **non-capability** — ツール/コマンド/サービスはあるが機能なし -capabilityモデルの詳細は [Plugin shapes](/ja-JP/plugins/architecture#plugin-shapes) を参照してください。 +機能モデルの詳細については [Plugin shapes](/ja-JP/plugins/architecture#plugin-shapes) を参照してください。 `--json` フラグは、スクリプトや監査に適した機械可読レポートを出力します。 -`inspect --all` は、shape、capability kinds、 -互換性通知、bundle capabilities、フック要約カラムを含む全体テーブルを表示します。 +`inspect --all` は、shape、capability kind、互換性通知、バンドル機能、およびフック概要の列を含む全体テーブルを表示します。 `info` は `inspect` のエイリアスです。 @@ -314,13 +241,9 @@ capabilityモデルの詳細は [Plugin shapes](/ja-JP/plugins/architecture#plug openclaw plugins doctor ``` -`doctor` はpluginの読み込みエラー、manifest/検出診断、 -互換性通知を報告します。問題がなければ `No plugin issues -detected.` と表示します。 +`doctor` は、Pluginの読み込みエラー、マニフェスト/検出diagnostics、および互換性通知を報告します。問題がない場合は `No plugin issues detected.` と表示します。 -`register`/`activate` export欠落のようなmodule-shape障害については、 -`OPENCLAW_PLUGIN_LOAD_DEBUG=1` を付けて再実行すると、 -診断出力にコンパクトなexport-shape要約が含まれます。 +`register`/`activate` エクスポートの欠落のようなモジュール形状の失敗については、`OPENCLAW_PLUGIN_LOAD_DEBUG=1` を付けて再実行すると、diagnostic出力にコンパクトなエクスポート形状の要約が含まれます。 ### Marketplace @@ -329,13 +252,10 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -marketplace listは、ローカルmarketplaceパス、`marketplace.json` パス、 -`owner/repo` のようなGitHub省略記法、GitHubリポジトリURL、またはgit URLを受け付けます。`--json` -は、解決されたsourceラベルに加えて、解析されたmarketplace manifestと -pluginエントリを出力します。 +マーケットプレイス一覧では、ローカルのマーケットプレイスパス、`marketplace.json` のパス、`owner/repo` のようなGitHub短縮表記、GitHubリポジトリURL、またはgit URLを受け付けます。`--json` は、解決されたソースラベルに加え、解析済みのマーケットプレイスマニフェストとPluginエントリを出力します。 ## 関連 -- [CLI reference](/ja-JP/cli) -- [Building plugins](/ja-JP/plugins/building-plugins) -- [Community plugins](/ja-JP/plugins/community) +- [CLIリファレンス](/ja-JP/cli) +- [Pluginのビルド](/ja-JP/plugins/building-plugins) +- [コミュニティPlugin](/ja-JP/plugins/community) diff --git a/docs/ja-JP/concepts/model-providers.md b/docs/ja-JP/concepts/model-providers.md index 1a23e524b..386770489 100644 --- a/docs/ja-JP/concepts/model-providers.md +++ b/docs/ja-JP/concepts/model-providers.md @@ -2,58 +2,58 @@ read_when: - プロバイダーごとのモデル設定リファレンスが必要です - モデルプロバイダー向けの設定例やCLIオンボーディングコマンドが必要です -summary: モデルプロバイダーの概要（設定例とCLIフロー付き） +summary: モデルプロバイダーの概要と設定例 + CLIフロー title: モデルプロバイダー x-i18n: - generated_at: "2026-04-24T08:57:02Z" + generated_at: "2026-04-24T15:21:28Z" model: gpt-5.4 provider: openai - source_hash: ac9bf48897446576d8bc339b340295691741a589863bb57b379c17a5519bffd7 + source_hash: 79258cb26fae7926c65b6fe0db938c7b5736a540b33bc24c1fad5ad706ac8204 source_path: concepts/model-providers.md workflow: 15 --- -このページでは**LLM/モデルプロバイダー**を扱います（WhatsApp/Telegram のようなチャットチャネルではありません）。 -モデル選択ルールについては、[/concepts/models](/ja-JP/concepts/models) を参照してください。 +このページでは、**LLM/モデルプロバイダー**（WhatsApp/Telegramのようなチャットチャネルではありません）を扱います。 +モデル選択ルールについては、[/concepts/models](/ja-JP/concepts/models)を参照してください。 ## クイックルール - モデル参照は `provider/model` を使用します（例: `opencode/claude-opus-4-6`）。 - `agents.defaults.models` は、設定されている場合は許可リストとして機能します。 - CLIヘルパー: `openclaw onboard`、`openclaw models list`、`openclaw models set ` -- `models.providers.*.models[].contextWindow` はネイティブなモデルメタデータです。`contextTokens` は実効ランタイム上限です。 +- `models.providers.*.models[].contextWindow` はネイティブなモデルメタデータで、`contextTokens` は実行時に有効な上限です。 - フォールバックルール、クールダウンプローブ、セッション上書きの永続化: [モデルフェイルオーバー](/ja-JP/concepts/model-failover) -- OpenAIファミリーのルートはプレフィックスごとに異なります: `openai/` はPIの直接OpenAI APIキープロバイダーを使用し、`openai-codex/` はPIのCodex OAuthを使用し、`openai/` に `agents.defaults.embeddedHarness.runtime: "codex"` を組み合わせるとネイティブなCodex app-server harnessを使用します。[OpenAI](/ja-JP/providers/openai) と [Codex harness](/ja-JP/plugins/codex-harness) を参照してください。 -- Plugin の自動有効化も同じ境界に従います: `openai-codex/` はOpenAI Plugin に属し、Codex Plugin は `embeddedHarness.runtime: "codex"` またはレガシーな `codex/` 参照によって有効になります。 -- GPT-5.5 は現在、サブスクリプション/OAuthルート経由で利用できます: PIでは `openai-codex/gpt-5.5`、またはCodex app-server harnessでは `openai/gpt-5.5` を使用します。`openai/gpt-5.5` の直接APIキールートは、OpenAIが公開APIでGPT-5.5を有効にするとサポートされます。それまでは `OPENAI_API_KEY` セットアップでは `openai/gpt-5.4` のようなAPI対応モデルを使用してください。 +- OpenAIファミリーのルートはプレフィックスごとに固有です: `openai/` はPI内の直接OpenAI APIキープロバイダーを使用し、`openai-codex/` はPI内でCodex OAuthを使用し、`openai/` に加えて `agents.defaults.embeddedHarness.runtime: "codex"` を指定するとネイティブCodex app-server harnessを使用します。[OpenAI](/ja-JP/providers/openai) と [Codex harness](/ja-JP/plugins/codex-harness) を参照してください。 +- Pluginの自動有効化も同じ境界に従います: `openai-codex/` はOpenAI Pluginに属し、Codex Pluginは `embeddedHarness.runtime: "codex"` または従来の `codex/` 参照によって有効になります。 +- GPT-5.5 は現在、サブスクリプション/OAuthルート経由で利用できます: PIでは `openai-codex/gpt-5.5`、またはCodex app-server harnessでは `openai/gpt-5.5` を使用します。`openai/gpt-5.5` の直接APIキールートは、OpenAIが公開APIでGPT-5.5を有効化するとサポートされます。それまでは、`OPENAI_API_KEY` セットアップでは `openai/gpt-5.4` のようなAPI対応モデルを使用してください。 -## Plugin 所有のプロバイダー動作 +## Pluginが所有するプロバイダー動作 -ほとんどのプロバイダー固有ロジックはプロバイダー Plugin（`registerProvider(...)`）内にあり、OpenClaw は汎用の推論ループを維持します。Plugin は、オンボーディング、モデルカタログ、認証env varのマッピング、転送/設定の正規化、ツールスキーマのクリーンアップ、フェイルオーバー分類、OAuth更新、使用量レポート、thinking/reasoningプロファイルなどを担当します。 +プロバイダー固有のロジックの大部分は、プロバイダーPlugin（`registerProvider(...)`）内にあり、OpenClawは汎用の推論ループを維持します。Pluginは、オンボーディング、モデルカタログ、認証env varマッピング、トランスポート/設定の正規化、ツールスキーマのクリーンアップ、フェイルオーバー分類、OAuth更新、使用量レポート、thinking/reasoningプロファイルなどを担当します。 -プロバイダーSDKフックの完全な一覧とバンドル済みPlugin の例は [プロバイダー Plugin](/ja-JP/plugins/sdk-provider-plugins) にあります。完全にカスタムなリクエスト実行器が必要なプロバイダーは、別のより深い拡張サーフェスになります。 +provider SDKフックの完全な一覧と同梱Pluginの例は、[プロバイダーPlugin](/ja-JP/plugins/sdk-provider-plugins) にあります。完全にカスタムなリクエスト実行器が必要なプロバイダーは、別のより深い拡張サーフェスになります。 -プロバイダーランタイムの `capabilities` は、共有ランナーメタデータ（プロバイダーファミリー、トランスクリプト/ツールの癖、転送/キャッシュのヒント）です。これは、Plugin が何を登録するか（テキスト推論、音声など）を説明する [公開 capability モデル](/ja-JP/plugins/architecture#public-capability-model) と同じではありません。 +プロバイダー実行時の `capabilities` は、共有ランナーメタデータ（プロバイダーファミリー、トランスクリプト/ツール処理の癖、トランスポート/キャッシュのヒント）です。これは、Pluginが何を登録するか（テキスト推論、音声など）を説明する [公開capabilityモデル](/ja-JP/plugins/architecture#public-capability-model) とは異なります。 ## APIキーのローテーション -- 選択されたプロバイダーで汎用のプロバイダーローテーションをサポートします。 -- 複数キーは次の方法で設定します: +- 選択されたプロバイダーで汎用的なプロバイダーローテーションをサポートします。 +- 複数キーは以下で設定します: - `OPENCLAW_LIVE__KEY`（単一のライブ上書き、最優先） - - `_API_KEYS`（カンマまたはセミコロン区切りリスト） - - `_API_KEY`（プライマリキー） + - `_API_KEYS`（カンマまたはセミコロン区切りのリスト） + - `_API_KEY`（プライマリーキー） - `_API_KEY_*`（番号付きリスト、例: `_API_KEY_1`） -- Googleプロバイダーでは、`GOOGLE_API_KEY` もフォールバックとして含まれます。 -- キーの選択順序は優先順位を保持し、値を重複排除します。 -- リクエストは、レート制限レスポンス時にのみ次のキーで再試行されます（例: `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、または定期的な使用量制限メッセージ）。 -- レート制限以外の失敗では即座に失敗し、キーローテーションは試行されません。 +- Googleプロバイダーでは、フォールバックとして `GOOGLE_API_KEY` も含まれます。 +- キーの選択順序は優先度を維持し、値は重複排除されます。 +- リクエストは、レート制限レスポンスの場合にのみ次のキーで再試行されます（例: `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`、または定期的な使用量制限メッセージ）。 +- レート制限以外の失敗は即座に失敗し、キーローテーションは試行されません。 - すべての候補キーが失敗した場合、最後の試行の最終エラーが返されます。 ## 組み込みプロバイダー（pi-aiカタログ） -OpenClaw には pi‑ai カタログが同梱されています。これらのプロバイダーでは `models.providers` 設定は**不要**です。認証を設定してモデルを選ぶだけです。 +OpenClawには pi‑ai カタログが同梱されています。これらのプロバイダーでは **`models.providers` 設定は不要** です。認証を設定してモデルを選ぶだけです。 ### OpenAI @@ -61,17 +61,17 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの - 認証: `OPENAI_API_KEY` - 任意のローテーション: `OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`、および `OPENCLAW_LIVE_OPENAI_KEY`（単一上書き） - モデル例: `openai/gpt-5.4`、`openai/gpt-5.4-mini` -- GPT-5.5 の直接APIサポートは、OpenAIがAPIでGPT-5.5を公開するとここで利用可能になります +- GPT-5.5の直接APIサポートは、OpenAIがAPIでGPT-5.5を公開すれば将来的にここで利用可能です - CLI: `openclaw onboard --auth-choice openai-api-key` -- デフォルト転送は `auto` です（WebSocket優先、SSEフォールバック） +- デフォルトのトランスポートは `auto` です（WebSocket優先、SSEフォールバック） - モデルごとの上書きは `agents.defaults.models["openai/"].params.transport` で行います（`"sse"`、`"websocket"`、または `"auto"`） -- OpenAI Responses WebSocketウォームアップは、`params.openaiWsWarmup`（`true`/`false`）によりデフォルトで有効です -- OpenAI優先処理は `agents.defaults.models["openai/"].params.serviceTier` で有効化できます -- `/fast` と `params.fastMode` は、直接の `openai/*` Responses リクエストを `api.openai.com` 上の `service_tier=priority` にマッピングします -- 共有の `/fast` トグルの代わりに明示的なティアを指定したい場合は `params.serviceTier` を使用してください -- 非表示のOpenClaw帰属ヘッダー（`originator`、`version`、`User-Agent`）は、汎用のOpenAI互換プロキシではなく、`api.openai.com` へのネイティブなOpenAIトラフィックにのみ適用されます -- ネイティブなOpenAIルートは Responses の `store`、prompt-cacheヒント、OpenAI reasoning互換のペイロード整形も維持します。プロキシルートでは維持されません -- `openai/gpt-5.3-codex-spark` は、実際のOpenAI APIリクエストで拒否され、現在のCodexカタログでも公開されていないため、OpenClaw では意図的に抑制されています +- OpenAI Responses WebSocketウォームアップは、`params.openaiWsWarmup`（`true`/`false`）でデフォルト有効です +- OpenAI優先処理は `agents.defaults.models["openai/"].params.serviceTier` で有効にできます +- `/fast` と `params.fastMode` は、直接の `openai/*` Responsesリクエストを `api.openai.com` 上の `service_tier=priority` にマップします +- 共有の `/fast` トグルではなく明示的なティアを使いたい場合は `params.serviceTier` を使用してください +- 非表示のOpenClaw attributionヘッダー（`originator`、`version`、`User-Agent`）は、汎用のOpenAI互換プロキシではなく、`api.openai.com` へのネイティブOpenAIトラフィックにのみ適用されます +- ネイティブOpenAIルートでは、Responsesの `store`、プロンプトキャッシュヒント、OpenAI reasoning互換のペイロード整形も維持されます。プロキシルートでは維持されません +- `openai/gpt-5.3-codex-spark` は、ライブOpenAI APIリクエストで拒否され、現在のCodexカタログにも公開されていないため、OpenClawでは意図的に抑止されています ```json5 { @@ -86,9 +86,9 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの - 任意のローテーション: `ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`、および `OPENCLAW_LIVE_ANTHROPIC_KEY`（単一上書き） - モデル例: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- 直接の公開Anthropicリクエストは、`api.anthropic.com` に送信されるAPIキー認証およびOAuth認証トラフィックを含め、共有の `/fast` トグルと `params.fastMode` をサポートします。OpenClaw はこれを Anthropic の `service_tier`（`auto` または `standard_only`）にマッピングします -- Anthropic に関する注記: Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されていると伝えられたため、Anthropicが新しいポリシーを公開しない限り、OpenClaw は Claude CLI の再利用と `claude -p` の使用をこの統合で認可済みとして扱います。 -- Anthropic setup-token は、サポートされるOpenClawトークンパスとして引き続き利用可能ですが、OpenClaw は現在、利用可能な場合は Claude CLI の再利用と `claude -p` を優先します。 +- 直接の公開Anthropicリクエストは、`api.anthropic.com` に送信されるAPIキー認証およびOAuth認証トラフィックを含め、共有の `/fast` トグルと `params.fastMode` をサポートします。OpenClawはこれをAnthropicの `service_tier`（`auto` と `standard_only`）にマップします +- Anthropicに関する注記: Anthropicのスタッフから、OpenClawスタイルのClaude CLI利用は再び許可されていると伝えられたため、Anthropicが新しいポリシーを公開しない限り、OpenClawはClaude CLIの再利用と `claude -p` の利用をこの統合で認可済みとして扱います。 +- Anthropic setup-token は、引き続きサポートされるOpenClawトークン経路として利用可能ですが、OpenClawは現在、利用可能な場合はClaude CLIの再利用と `claude -p` を優先します。 ```json5 { @@ -101,17 +101,17 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの - プロバイダー: `openai-codex` - 認証: OAuth（ChatGPT） - PIモデル参照: `openai-codex/gpt-5.5` -- ネイティブなCodex app-server harness参照: `openai/gpt-5.5` と `agents.defaults.embeddedHarness.runtime: "codex"` -- レガシーモデル参照: `codex/gpt-*` -- Plugin の境界: `openai-codex/*` はOpenAI Plugin を読み込みます。ネイティブなCodex app-server Plugin は、Codex harnessランタイムまたはレガシーな `codex/*` 参照によってのみ選択されます。 +- ネイティブCodex app-server harness参照: `agents.defaults.embeddedHarness.runtime: "codex"` を指定した `openai/gpt-5.5` +- 従来のモデル参照: `codex/gpt-*` +- Plugin境界: `openai-codex/*` はOpenAI Pluginを読み込みます。ネイティブCodex app-server Pluginが選択されるのは、Codex harness runtimeまたは従来の `codex/*` 参照による場合のみです。 - CLI: `openclaw onboard --auth-choice openai-codex` または `openclaw models auth login --provider openai-codex` -- デフォルト転送は `auto` です（WebSocket優先、SSEフォールバック） +- デフォルトのトランスポートは `auto` です（WebSocket優先、SSEフォールバック） - PIモデルごとの上書きは `agents.defaults.models["openai-codex/"].params.transport` で行います（`"sse"`、`"websocket"`、または `"auto"`） -- `params.serviceTier` もネイティブなCodex Responses リクエスト（`chatgpt.com/backend-api`）で転送されます -- 非表示のOpenClaw帰属ヘッダー（`originator`、`version`、`User-Agent`）は、汎用のOpenAI互換プロキシではなく、`chatgpt.com/backend-api` へのネイティブなCodexトラフィックにのみ付与されます -- 直接の `openai/*` と同じ `/fast` トグルおよび `params.fastMode` 設定を共有し、OpenClaw はこれを `service_tier=priority` にマッピングします -- `openai-codex/gpt-5.5` はネイティブな `contextWindow = 1000000` とデフォルトのランタイム `contextTokens = 272000` を維持します。ランタイム上限は `models.providers.openai-codex.models[].contextTokens` で上書きしてください -- ポリシー注記: OpenAI Codex OAuth は、OpenClaw のような外部ツール/ワークフロー向けに明示的にサポートされています。 +- `params.serviceTier` もネイティブCodex Responsesリクエスト（`chatgpt.com/backend-api`）で転送されます +- 非表示のOpenClaw attributionヘッダー（`originator`、`version`、`User-Agent`）は、汎用のOpenAI互換プロキシではなく、`chatgpt.com/backend-api` へのネイティブCodexトラフィックにのみ付与されます +- 直接の `openai/*` と同じ `/fast` トグルおよび `params.fastMode` 設定を共有し、OpenClawはこれを `service_tier=priority` にマップします +- `openai-codex/gpt-5.5` はネイティブの `contextWindow = 1000000` とデフォルトの実行時 `contextTokens = 272000` を維持します。実行時上限は `models.providers.openai-codex.models[].contextTokens` で上書きできます +- ポリシーに関する注記: OpenAI Codex OAuth は、OpenClawのような外部ツール/ワークフロー向けに明示的にサポートされています。 - 現在のGPT-5.5アクセスは、OpenAIが公開APIでGPT-5.5を有効にするまで、このOAuth/サブスクリプションルートを使用します。 ```json5 @@ -134,15 +134,15 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの ### その他のサブスクリプション型ホストオプション -- [Qwen Cloud](/ja-JP/providers/qwen): Qwen CloudプロバイダーサーフェスとAlibaba DashScopeおよびCoding Planエンドポイントのマッピング -- [MiniMax](/ja-JP/providers/minimax): MiniMax Coding Plan OAuth またはAPIキーアクセス -- [GLM Models](/ja-JP/providers/glm): Z.AI Coding Plan または一般APIエンドポイント +- [Qwen Cloud](/ja-JP/providers/qwen): Qwen Cloudプロバイダーサーフェス、およびAlibaba DashScopeとCoding Planエンドポイントのマッピング +- [MiniMax](/ja-JP/providers/minimax): MiniMax Coding Plan OAuthまたはAPIキーアクセス +- [GLM Models](/ja-JP/providers/glm): Z.AI Coding Planまたは一般APIエンドポイント ### OpenCode - 認証: `OPENCODE_API_KEY`（または `OPENCODE_ZEN_API_KEY`） -- Zenランタイムプロバイダー: `opencode` -- Goランタイムプロバイダー: `opencode-go` +- Zen runtimeプロバイダー: `opencode` +- Go runtimeプロバイダー: `opencode-go` - モデル例: `opencode/claude-opus-4-6`、`opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` または `openclaw onboard --auth-choice opencode-go` @@ -158,25 +158,25 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの - 認証: `GEMINI_API_KEY` - 任意のローテーション: `GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` フォールバック、および `OPENCLAW_LIVE_GEMINI_KEY`（単一上書き） - モデル例: `google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` -- 互換性: `google/gemini-3.1-flash-preview` を使用するレガシーなOpenClaw設定は `google/gemini-3-flash-preview` に正規化されます +- 互換性: `google/gemini-3.1-flash-preview` を使用する従来のOpenClaw設定は、`google/gemini-3-flash-preview` に正規化されます - CLI: `openclaw onboard --auth-choice gemini-api-key` -- 直接のGemini実行は、`agents.defaults.models["google/"].params.cachedContent`（またはレガシーな `cached_content`）も受け付け、プロバイダーネイティブな `cachedContents/...` ハンドルを転送します。GeminiのキャッシュヒットはOpenClawの `cacheRead` として表面化します +- 直接のGemini実行では、`agents.defaults.models["google/"].params.cachedContent`（または従来の `cached_content`）も受け付け、プロバイダーネイティブな `cachedContents/...` ハンドルを転送します。GeminiのキャッシュヒットはOpenClawの `cacheRead` として表示されます ### Google Vertex と Gemini CLI - プロバイダー: `google-vertex`、`google-gemini-cli` -- 認証: Vertex は gcloud ADC を使用し、Gemini CLI は独自のOAuthフローを使用します -- 注意: OpenClaw における Gemini CLI OAuth は非公式の統合です。サードパーティークライアントの使用後にGoogleアカウント制限が発生したと報告したユーザーもいます。利用する場合はGoogleの利用規約を確認し、重要でないアカウントを使用してください。 -- Gemini CLI OAuth は、バンドル済みの `google` Plugin の一部として提供されます。 - - まず Gemini CLI をインストールします: +- 認証: Vertexはgcloud ADCを使用し、Gemini CLIはそのOAuthフローを使用します +- 注意: OpenClawでのGemini CLI OAuthは非公式な統合です。サードパーティークライアント使用後にGoogleアカウント制限がかかったという報告があります。利用する場合はGoogleの利用規約を確認し、重要でないアカウントを使ってください。 +- Gemini CLI OAuth は、同梱の `google` Pluginの一部として提供されています。 + - まずGemini CLIをインストールします: - `brew install gemini-cli` - または `npm install -g @google/gemini-cli` - 有効化: `openclaw plugins enable google` - ログイン: `openclaw models auth login --provider google-gemini-cli --set-default` - デフォルトモデル: `google-gemini-cli/gemini-3-flash-preview` - - 注記: `openclaw.json` にクライアントIDやシークレットを貼り付ける必要は**ありません**。CLIログインフローは、Gatewayホスト上の認証プロファイルにトークンを保存します。 - - ログイン後にリクエストが失敗する場合は、Gatewayホストで `GOOGLE_CLOUD_PROJECT` または `GOOGLE_CLOUD_PROJECT_ID` を設定してください。 - - Gemini CLI のJSON応答は `response` から解析され、使用量は `stats` にフォールバックされます。`stats.cached` は OpenClaw の `cacheRead` に正規化されます。 + - 注記: `openclaw.json` にclient idやsecretを貼り付ける必要は**ありません**。CLIログインフローは、gatewayホスト上の認証プロファイルにトークンを保存します。 + - ログイン後にリクエストが失敗する場合は、gatewayホストで `GOOGLE_CLOUD_PROJECT` または `GOOGLE_CLOUD_PROJECT_ID` を設定してください。 + - Gemini CLIのJSON返信は `response` から解析され、使用量は `stats` にフォールバックし、`stats.cached` はOpenClawの `cacheRead` に正規化されます。 ### Z.AI（GLM） @@ -185,7 +185,7 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの - モデル例: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - エイリアス: `z.ai/*` と `z-ai/*` は `zai/*` に正規化されます - - `zai-api-key` は一致するZ.AIエンドポイントを自動検出します。`zai-coding-global`、`zai-coding-cn`、`zai-global`、`zai-cn` は特定のサーフェスを強制します + - `zai-api-key` は一致するZ.AIエンドポイントを自動検出し、`zai-coding-global`、`zai-coding-cn`、`zai-global`、`zai-cn` は特定のサーフェスを強制します ### Vercel AI Gateway @@ -201,18 +201,19 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの - モデル例: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - ベースURL: `https://api.kilo.ai/api/gateway/` -- 静的フォールバックカタログには `kilocode/kilo/auto` が同梱されています。ライブの `https://api.kilo.ai/api/gateway/models` 検出により、ランタイムカタログがさらに拡張される場合があります。 -- `kilocode/kilo/auto` の背後にある正確な上流ルーティングは、OpenClaw にハードコードされておらず、Kilo Gateway が管理します。 +- 静的フォールバックカタログには `kilocode/kilo/auto` が同梱されています。ライブの `https://api.kilo.ai/api/gateway/models` 検出により、実行時カタログがさらに拡張される場合があります。 +- `kilocode/kilo/auto` の背後にある正確なアップストリームルーティングは、OpenClawにハードコードされておらず、Kilo Gatewayが管理します。 セットアップの詳細は [/providers/kilocode](/ja-JP/providers/kilocode) を参照してください。 -### その他のバンドル済みプロバイダー Plugin +### その他の同梱プロバイダーPlugin | プロバイダー | Id | 認証env | モデル例 | | ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | | BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | | Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | | GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | | Groq | `groq` | `GROQ_API_KEY` | — | | Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` または `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | @@ -233,12 +234,12 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -知っておくとよい癖: +知っておくと役立つ癖: -- **OpenRouter** は、アプリ帰属ヘッダーと Anthropic の `cache_control` マーカーを、検証済みの `openrouter.ai` ルートでのみ適用します。プロキシ型のOpenAI互換パスとして、ネイティブOpenAI専用の整形（`serviceTier`、Responses の `store`、prompt-cacheヒント、OpenAI reasoning互換）はスキップします。Geminiベースの参照では、プロキシGeminiの thought-signature サニタイズのみ維持されます。 -- **Kilo Gateway** のGeminiベース参照も同じプロキシGeminiサニタイズパスに従います。`kilocode/kilo/auto` およびその他のプロキシreasoning非対応参照では、プロキシreasoning挿入をスキップします。 -- **MiniMax** のAPIキーオンボーディングは、`input: ["text", "image"]` を持つ明示的なM2.7モデル定義を書き込みます。バンドル済みカタログでは、その設定が具体化されるまではチャット参照をテキスト専用として扱います。 -- **xAI** は xAI Responses パスを使用します。`/fast` または `params.fastMode: true` は、`grok-3`、`grok-3-mini`、`grok-4`、`grok-4-0709` をそれぞれの `*-fast` バリアントに書き換えます。`tool_stream` はデフォルトで有効です。無効にするには `agents.defaults.models["xai/"].params.tool_stream=false` を設定します。 +- **OpenRouter** は、検証済みの `openrouter.ai` ルートでのみアプリattributionヘッダーとAnthropicの `cache_control` マーカーを適用します。プロキシ型のOpenAI互換パスとして、ネイティブOpenAI専用の整形（`serviceTier`、Responses `store`、プロンプトキャッシュヒント、OpenAI reasoning互換）はスキップします。Geminiベースの参照は、プロキシGeminiのthought-signatureサニタイズのみ維持されます。 +- **Kilo Gateway** のGeminiベース参照も同じプロキシGeminiサニタイズ経路に従います。`kilocode/kilo/auto` と、その他のプロキシでreasoning未対応の参照は、プロキシreasoning注入をスキップします。 +- **MiniMax** のAPIキーオンボーディングは、`input: ["text", "image"]` を持つ明示的なM2.7モデル定義を書き込みます。同梱カタログでは、その設定が具体化されるまでchat参照はtext専用のままです。 +- **xAI** はxAI Responsesパスを使用します。`/fast` または `params.fastMode: true` は、`grok-3`、`grok-3-mini`、`grok-4`、`grok-4-0709` をそれぞれの `*-fast` バリアントに書き換えます。`tool_stream` はデフォルトで有効です。無効にするには `agents.defaults.models["xai/"].params.tool_stream=false` を使用します。 - **Cerebras** のGLMモデルは `zai-glm-4.7` / `zai-glm-4.6` を使用します。OpenAI互換のベースURLは `https://api.cerebras.ai/v1` です。 ## `models.providers` 経由のプロバイダー（カスタム/ベースURL） @@ -246,21 +247,21 @@ OpenClaw には pi‑ai カタログが同梱されています。これらの `models.providers`（または `models.json`）を使用して、**カスタム**プロバイダーや OpenAI/Anthropic互換プロキシを追加します。 -以下のバンドル済みプロバイダー Plugin の多くは、すでにデフォルトカタログを公開しています。 -明示的な `models.providers.` エントリを使用するのは、デフォルトの -ベースURL、ヘッダー、またはモデル一覧を上書きしたい場合だけです。 +以下の同梱プロバイダーPluginの多くは、すでにデフォルトカタログを公開しています。 +デフォルトのベースURL、ヘッダー、またはモデル一覧を上書きしたい場合にのみ、 +明示的な `models.providers.` エントリーを使用してください。 -### Moonshot AI (Kimi) +### Moonshot AI（Kimi） -Moonshot はバンドル済みプロバイダー Plugin として提供されます。デフォルトでは組み込みプロバイダーを使用し、 -ベースURLまたはモデルメタデータを上書きする必要がある場合のみ、明示的な `models.providers.moonshot` エントリを追加してください。 +Moonshot は同梱プロバイダーPluginとして提供されています。通常は組み込みプロバイダーを使用し、 +ベースURLまたはモデルメタデータを上書きする必要がある場合のみ、明示的な `models.providers.moonshot` エントリーを追加してください。 - プロバイダー: `moonshot` - 認証: `MOONSHOT_API_KEY` - モデル例: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` または `openclaw onboard --auth-choice moonshot-api-key-cn` -Kimi K2 のモデルId: +Kimi K2モデルID: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -293,7 +294,7 @@ Kimi K2 のモデルId: ### Kimi Coding -Kimi Coding は Moonshot AI のAnthropic互換エンドポイントを使用します。 +Kimi Coding は、Moonshot AIのAnthropic互換エンドポイントを使用します。 - プロバイダー: `kimi` - 認証: `KIMI_API_KEY` @@ -308,13 +309,13 @@ Kimi Coding は Moonshot AI のAnthropic互換エンドポイントを使用し } ``` -レガシーな `kimi/k2p5` も互換モデルIdとして引き続き受け付けられます。 +従来の `kimi/k2p5` も、互換モデルIDとして引き続き受け付けられます。 -### Volcano Engine (Doubao) +### Volcano Engine（Doubao） -Volcano Engine（火山引擎）は、中国でDoubaoおよびその他のモデルへのアクセスを提供します。 +Volcano Engine（火山引擎）は、中国でDoubaoやその他のモデルへのアクセスを提供します。 -- プロバイダー: `volcengine`（コーディング用: `volcengine-plan`） +- プロバイダー: `volcengine`（コーディング: `volcengine-plan`） - 認証: `VOLCANO_ENGINE_API_KEY` - モデル例: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -327,20 +328,20 @@ Volcano Engine（火山引擎）は、中国でDoubaoおよびその他のモデ } ``` -オンボーディングではデフォルトでコーディング用サーフェスを使用しますが、一般向けの `volcengine/*` +オンボーディングはデフォルトでコーディングサーフェスを使用しますが、一般的な `volcengine/*` カタログも同時に登録されます。 -オンボーディング/設定のモデルピッカーでは、Volcengine の認証選択は +オンボーディング/モデル設定ピッカーでは、Volcengineの認証選択は `volcengine/*` と `volcengine-plan/*` の両方の行を優先します。これらのモデルがまだ読み込まれていない場合、 -OpenClaw は空のプロバイダースコープピッカーを表示する代わりに、フィルタなしカタログへフォールバックします。 +OpenClawは空のプロバイダースコープ付きピッカーを表示する代わりに、フィルターなしカタログにフォールバックします。 利用可能なモデル: -- `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8) +- `volcengine/doubao-seed-1-8-251228`（Doubao Seed 1.8） - `volcengine/doubao-seed-code-preview-251028` -- `volcengine/kimi-k2-5-260127` (Kimi K2.5) -- `volcengine/glm-4-7-251222` (GLM 4.7) -- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) +- `volcengine/kimi-k2-5-260127`（Kimi K2.5） +- `volcengine/glm-4-7-251222`（GLM 4.7） +- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） コーディングモデル（`volcengine-plan`）: @@ -352,9 +353,9 @@ OpenClaw は空のプロバイダースコープピッカーを表示する代 ### BytePlus（International） -BytePlus ARK は、国際ユーザー向けに Volcano Engine と同じモデルへのアクセスを提供します。 +BytePlus ARK は、国際ユーザー向けにVolcano Engineと同じモデルへのアクセスを提供します。 -- プロバイダー: `byteplus`（コーディング用: `byteplus-plan`） +- プロバイダー: `byteplus`（コーディング: `byteplus-plan`） - 認証: `BYTEPLUS_API_KEY` - モデル例: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -367,18 +368,18 @@ BytePlus ARK は、国際ユーザー向けに Volcano Engine と同じモデル } ``` -オンボーディングではデフォルトでコーディング用サーフェスを使用しますが、一般向けの `byteplus/*` +オンボーディングはデフォルトでコーディングサーフェスを使用しますが、一般的な `byteplus/*` カタログも同時に登録されます。 -オンボーディング/設定のモデルピッカーでは、BytePlus の認証選択は +オンボーディング/モデル設定ピッカーでは、BytePlusの認証選択は `byteplus/*` と `byteplus-plan/*` の両方の行を優先します。これらのモデルがまだ読み込まれていない場合、 -OpenClaw は空のプロバイダースコープピッカーを表示する代わりに、フィルタなしカタログへフォールバックします。 +OpenClawは空のプロバイダースコープ付きピッカーを表示する代わりに、フィルターなしカタログにフォールバックします。 利用可能なモデル: -- `byteplus/seed-1-8-251228` (Seed 1.8) -- `byteplus/kimi-k2-5-260127` (Kimi K2.5) -- `byteplus/glm-4-7-251222` (GLM 4.7) +- `byteplus/seed-1-8-251228`（Seed 1.8） +- `byteplus/kimi-k2-5-260127`（Kimi K2.5） +- `byteplus/glm-4-7-251222`（GLM 4.7） コーディングモデル（`byteplus-plan`）: @@ -390,7 +391,7 @@ OpenClaw は空のプロバイダースコープピッカーを表示する代 ### Synthetic -Synthetic は、`synthetic` プロバイダーの背後で Anthropic 互換モデルを提供します。 +Synthetic は、`synthetic` プロバイダーの背後でAnthropic互換モデルを提供します。 - プロバイダー: `synthetic` - 認証: `SYNTHETIC_API_KEY` @@ -424,31 +425,30 @@ MiniMax はカスタムエンドポイントを使用するため、`models.prov - MiniMax OAuth（CN）: `--auth-choice minimax-cn-oauth` - MiniMax APIキー（Global）: `--auth-choice minimax-global-api` - MiniMax APIキー（CN）: `--auth-choice minimax-cn-api` -- 認証: `minimax` では `MINIMAX_API_KEY`、`minimax-portal` では `MINIMAX_OAUTH_TOKEN` または - `MINIMAX_API_KEY` +- 認証: `minimax` では `MINIMAX_API_KEY`、`minimax-portal` では `MINIMAX_OAUTH_TOKEN` または `MINIMAX_API_KEY` セットアップの詳細、モデルオプション、設定スニペットについては [/providers/minimax](/ja-JP/providers/minimax) を参照してください。 -MiniMax の Anthropic 互換ストリーミングパスでは、明示的に設定しない限り、 -OpenClaw はデフォルトで thinking を無効にし、`/fast on` は +MiniMaxのAnthropic互換ストリーミングパスでは、明示的に設定しない限り、 +OpenClawはデフォルトでthinkingを無効にし、`/fast on` は `MiniMax-M2.7` を `MiniMax-M2.7-highspeed` に書き換えます。 -Plugin 所有の capability 分割: +Pluginが所有するcapability分割: -- テキスト/チャットのデフォルトは `minimax/MiniMax-M2.7` のままです +- テキスト/chatのデフォルトは `minimax/MiniMax-M2.7` のままです - 画像生成は `minimax/image-01` または `minimax-portal/image-01` です -- 画像理解は、両方の MiniMax 認証パスで Plugin 所有の `MiniMax-VL-01` です +- 画像理解は、両方のMiniMax認証パスでPlugin所有の `MiniMax-VL-01` です - Web検索はプロバイダーid `minimax` のままです ### LM Studio -LM Studio はネイティブAPIを使用するバンドル済みプロバイダー Plugin として提供されます。 +LM Studio は、ネイティブAPIを使用する同梱プロバイダーPluginとして提供されています。 - プロバイダー: `lmstudio` - 認証: `LM_API_TOKEN` -- デフォルト推論ベースURL: `http://localhost:1234/v1` +- デフォルトの推論ベースURL: `http://localhost:1234/v1` -次にモデルを設定します（`http://localhost:1234/api/v1/models` が返す ID のいずれかに置き換えてください）: +その後、モデルを設定します（`http://localhost:1234/api/v1/models` が返すIDのいずれかに置き換えてください）: ```json5 { @@ -458,11 +458,12 @@ LM Studio はネイティブAPIを使用するバンドル済みプロバイダ } ``` -OpenClaw は、検出と自動ロードに LM Studio ネイティブの `/api/v1/models` と `/api/v1/models/load` を使用し、デフォルトでは推論に `/v1/chat/completions` を使用します。セットアップとトラブルシューティングについては [/providers/lmstudio](/ja-JP/providers/lmstudio) を参照してください。 +OpenClawは、検出と自動読み込みにLM Studioネイティブの `/api/v1/models` と `/api/v1/models/load` を使用し、デフォルトでは推論に `/v1/chat/completions` を使用します。 +セットアップとトラブルシューティングについては [/providers/lmstudio](/ja-JP/providers/lmstudio) を参照してください。 ### Ollama -Ollama はバンドル済みプロバイダー Plugin として提供され、Ollama のネイティブAPIを使用します: +Ollama は同梱プロバイダーPluginとして提供され、OllamaのネイティブAPIを使用します。 - プロバイダー: `ollama` - 認証: 不要（ローカルサーバー） @@ -470,7 +471,7 @@ Ollama はバンドル済みプロバイダー Plugin として提供され、Ol - インストール: [https://ollama.com/download](https://ollama.com/download) ```bash -# Ollama をインストールしてから、モデルを pull します: +# Ollamaをインストールしてから、モデルをpullします: ollama pull llama3.3 ``` @@ -482,18 +483,19 @@ ollama pull llama3.3 } ``` -Ollama は、`OLLAMA_API_KEY` でオプトインすると `http://127.0.0.1:11434` でローカル検出され、 -バンドル済みプロバイダー Plugin によって Ollama が `openclaw onboard` とモデルピッカーに直接追加されます。オンボーディング、クラウド/ローカルモード、カスタム設定については [/providers/ollama](/ja-JP/providers/ollama) +Ollamaは、`OLLAMA_API_KEY` でオプトインするとローカルの `http://127.0.0.1:11434` で検出され、 +同梱プロバイダーPluginがOllamaを `openclaw onboard` とモデルピッカーに直接追加します。 +オンボーディング、クラウド/ローカルモード、カスタム設定については [/providers/ollama](/ja-JP/providers/ollama) を参照してください。 ### vLLM vLLM は、ローカル/セルフホストのOpenAI互換 -サーバー向けバンドル済みプロバイダー Plugin として提供されます。 +サーバー向けの同梱プロバイダーPluginとして提供されています。 - プロバイダー: `vllm` -- 認証: 任意（サーバー設定による） -- デフォルトベースURL: `http://127.0.0.1:8000/v1` +- 認証: 任意（サーバーによります） +- デフォルトのベースURL: `http://127.0.0.1:8000/v1` ローカルで自動検出にオプトインするには（サーバーが認証を強制しない場合は任意の値で動作します）: @@ -501,7 +503,7 @@ vLLM は、ローカル/セルフホストのOpenAI互換 export VLLM_API_KEY="vllm-local" ``` -次にモデルを設定します（`/v1/models` が返す ID のいずれかに置き換えてください）: +その後、モデルを設定します（`/v1/models` が返すIDのいずれかに置き換えてください）: ```json5 { @@ -516,19 +518,20 @@ export VLLM_API_KEY="vllm-local" ### SGLang SGLang は、高速なセルフホスト -OpenAI互換サーバー向けバンドル済みプロバイダー Plugin として提供されます。 +OpenAI互換サーバー向けの同梱プロバイダーPluginとして提供されています。 - プロバイダー: `sglang` -- 認証: 任意（サーバー設定による） -- デフォルトベースURL: `http://127.0.0.1:30000/v1` +- 認証: 任意（サーバーによります） +- デフォルトのベースURL: `http://127.0.0.1:30000/v1` -ローカルで自動検出にオプトインするには（サーバーが認証を強制しない場合は任意の値で動作します）: +ローカルで自動検出にオプトインするには（サーバーが認証を強制しない場合は +任意の値で動作します）: ```bash export SGLANG_API_KEY="sglang-local" ``` -次にモデルを設定します（`/v1/models` が返す ID のいずれかに置き換えてください）: +その後、モデルを設定します（`/v1/models` が返すIDのいずれかに置き換えてください）: ```json5 { @@ -540,7 +543,7 @@ export SGLANG_API_KEY="sglang-local" 詳細は [/providers/sglang](/ja-JP/providers/sglang) を参照してください。 -### ローカルプロキシ（LM Studio、vLLM、LiteLLM など） +### ローカルプロキシ（LM Studio、vLLM、LiteLLMなど） 例（OpenAI互換）: @@ -578,22 +581,19 @@ export SGLANG_API_KEY="sglang-local" 注記: - カスタムプロバイダーでは、`reasoning`、`input`、`cost`、`contextWindow`、`maxTokens` は任意です。 - 省略した場合、OpenClaw のデフォルトは次のとおりです: + 省略時、OpenClawのデフォルトは以下です: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` - 推奨: プロキシ/モデルの制限に一致する明示的な値を設定してください。 -- ネイティブでないエンドポイント上の `api: "openai-completions"` では（ホストが `api.openai.com` ではない空でない `baseUrl`）、OpenClaw は、サポートされない `developer` ロールによるプロバイダーの400エラーを避けるため、`compat.supportsDeveloperRole: false` を強制します。 -- プロキシ型のOpenAI互換ルートでも、ネイティブOpenAI専用のリクエスト整形はスキップされます: - `service_tier` なし、Responses の `store` なし、prompt-cacheヒントなし、 - OpenAI reasoning互換のペイロード整形なし、非表示のOpenClaw帰属 - ヘッダーなし。 -- `baseUrl` が空または省略されている場合、OpenClaw はデフォルトのOpenAI動作を維持します（`api.openai.com` に解決されます）。 -- 安全のため、ネイティブでない `openai-completions` エンドポイントでは、明示的な `compat.supportsDeveloperRole: true` も引き続き上書きされます。 +- ネイティブでないエンドポイント上の `api: "openai-completions"` では（ホストが `api.openai.com` ではない空でない `baseUrl`）、OpenClawは、未対応の `developer` ロールによるプロバイダー400エラーを避けるため、`compat.supportsDeveloperRole: false` を強制します。 +- プロキシ型のOpenAI互換ルートでも、ネイティブOpenAI専用のリクエスト整形はスキップされます。`service_tier` なし、Responses `store` なし、プロンプトキャッシュヒントなし、OpenAI reasoning互換ペイロード整形なし、非表示のOpenClaw attributionヘッダーなしです。 +- `baseUrl` が空または省略されている場合、OpenClawはデフォルトのOpenAI動作を維持します（これは `api.openai.com` に解決されます）。 +- 安全性のため、ネイティブでない `openai-completions` エンドポイントでは、明示的な `compat.supportsDeveloperRole: true` も引き続き上書きされます。 -## CLIの例 +## CLI例 ```bash openclaw onboard --auth-choice opencode-zen @@ -601,11 +601,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -関連項目: 完全な設定例については [/gateway/configuration](/ja-JP/gateway/configuration) を参照してください。 +参照: 完全な設定例については [/gateway/configuration](/ja-JP/gateway/configuration) を参照してください。 ## 関連 -- [Models](/ja-JP/concepts/models) — モデル設定とエイリアス -- [Model Failover](/ja-JP/concepts/model-failover) — フォールバックチェーンと再試行の動作 -- [Configuration Reference](/ja-JP/gateway/config-agents#agent-defaults) — モデル設定キー -- [Providers](/ja-JP/providers) — プロバイダーごとのセットアップガイド +- [モデル](/ja-JP/concepts/models) — モデル設定とエイリアス +- [モデルフェイルオーバー](/ja-JP/concepts/model-failover) — フォールバックチェーンと再試行動作 +- [設定リファレンス](/ja-JP/gateway/config-agents#agent-defaults) — モデル設定キー +- [プロバイダー](/ja-JP/providers) — プロバイダーごとのセットアップガイド diff --git a/docs/ja-JP/pi.md b/docs/ja-JP/pi.md index d9025b436..203cf1466 100644 --- a/docs/ja-JP/pi.md +++ b/docs/ja-JP/pi.md @@ -1,126 +1,126 @@ --- read_when: - - OpenClaw における Pi SDK 統合設計を理解する შემთხვევაში - - Pi 向けのエージェントセッションライフサイクル、tooling、またはプロバイダー配線を変更する ক্ষেত্রে -summary: OpenClaw の埋め込み Pi エージェント統合とセッションライフサイクルのアーキテクチャ -title: Pi 統合アーキテクチャ + - OpenClawにおけるPi SDK統合設計の理解 + - Piのエージェントセッションライフサイクル、ツール、またはプロバイダー接続の変更 +summary: OpenClawの組み込みPiエージェント統合のアーキテクチャとセッションライフサイクル +title: Pi統合アーキテクチャ x-i18n: - generated_at: "2026-04-24T05:07:09Z" + generated_at: "2026-04-24T15:21:27Z" model: gpt-5.4 provider: openai - source_hash: 3c0c490cad121a65d557a72887ea619a7d0cff34a62220752214185c9148dc0b + source_hash: 0c0b019ff6d35f6fdcd57b56edd1945e62a96bb4b34e312d7fb0c627f01287f1 source_path: pi.md workflow: 15 --- -このドキュメントでは、OpenClaw が [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) と、その兄弟パッケージ（`pi-ai`、`pi-agent-core`、`pi-tui`）をどのように統合して AI エージェント機能を実現しているかを説明します。 +このドキュメントでは、OpenClawがAIエージェント機能を実現するために、[pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) とその関連パッケージ（`pi-ai`、`pi-agent-core`、`pi-tui`）をどのように統合しているかを説明します。 ## 概要 -OpenClaw は、メッセージング Gateway アーキテクチャに AI コーディングエージェントを埋め込むために pi SDK を使います。pi をサブプロセスとして起動したり RPC モードを使ったりするのではなく、OpenClaw は `createAgentSession()` を通じて pi の `AgentSession` を直接 import して生成します。この埋め込みアプローチにより、次が可能になります。 +OpenClawは、メッセージングGatewayアーキテクチャにAIコーディングエージェントを組み込むためにpi SDKを使用します。piをサブプロセスとして起動したり、RPCモードを使ったりする代わりに、OpenClawは `createAgentSession()` を通じてpiの `AgentSession` を直接インポートしてインスタンス化します。この組み込みアプローチにより、以下が可能になります。 - セッションライフサイクルとイベント処理の完全な制御 -- カスタム tool 注入（メッセージング、sandbox、チャネル固有アクション） -- チャネル/コンテキストごとのシステムプロンプトカスタマイズ -- 分岐/Compaction をサポートするセッション永続化 -- フェイルオーバー付きのマルチアカウント auth profile ローテーション +- カスタムツールの注入（メッセージング、sandbox、チャネル固有のアクション） +- チャネルやコンテキストごとのシステムプロンプトのカスタマイズ +- ブランチ分岐/Compaction対応のセッション永続化 +- フェイルオーバー付きのマルチアカウント認証プロファイルローテーション - プロバイダー非依存のモデル切り替え ## パッケージ依存関係 ```json { - "@mariozechner/pi-agent-core": "0.68.1", - "@mariozechner/pi-ai": "0.68.1", - "@mariozechner/pi-coding-agent": "0.68.1", - "@mariozechner/pi-tui": "0.68.1" + "@mariozechner/pi-agent-core": "0.70.2", + "@mariozechner/pi-ai": "0.70.2", + "@mariozechner/pi-coding-agent": "0.70.2", + "@mariozechner/pi-tui": "0.70.2" } ``` | パッケージ | 目的 | | ----------------- | ------------------------------------------------------------------------------------------------------ | -| `pi-ai` | 中核 LLM 抽象化: `Model`、`streamSimple`、メッセージ型、プロバイダー API | -| `pi-agent-core` | エージェントループ、tool 実行、`AgentMessage` 型 | -| `pi-coding-agent` | 高レベル SDK: `createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、組み込み tools | -| `pi-tui` | ターミナル UI コンポーネント（OpenClaw のローカル TUI モードで使用） | +| `pi-ai` | コアLLM抽象化: `Model`、`streamSimple`、メッセージ型、プロバイダーAPI | +| `pi-agent-core` | エージェントループ、ツール実行、`AgentMessage` 型 | +| `pi-coding-agent` | 高水準SDK: `createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、組み込みツール | +| `pi-tui` | ターミナルUIコンポーネント（OpenClawのローカルTUIモードで使用） | -## ファイル構成 +## ファイル構造 ``` src/agents/ -├── pi-embedded-runner.ts # pi-embedded-runner/ からの再エクスポート +├── pi-embedded-runner.ts # pi-embedded-runner/ から再エクスポート ├── pi-embedded-runner/ -│ ├── run.ts # メインエントリー: runEmbeddedPiAgent() +│ ├── run.ts # メインエントリ: runEmbeddedPiAgent() │ ├── run/ │ │ ├── attempt.ts # セッション設定を含む単一試行ロジック │ │ ├── params.ts # RunEmbeddedPiAgentParams 型 -│ │ ├── payloads.ts # 実行結果から応答ペイロードを構築 -│ │ ├── images.ts # vision モデル画像注入 +│ │ ├── payloads.ts # 実行結果からレスポンスペイロードを構築 +│ │ ├── images.ts # Visionモデル向け画像注入 │ │ └── types.ts # EmbeddedRunAttemptResult │ ├── abort.ts # 中断エラー検出 -│ ├── cache-ttl.ts # コンテキスト pruning 用のキャッシュ TTL 追跡 -│ ├── compact.ts # 手動/自動 Compaction ロジック -│ ├── extensions.ts # 埋め込み実行用の pi extension 読み込み -│ ├── extra-params.ts # プロバイダー固有の stream パラメーター -│ ├── google.ts # Google/Gemini のターン順序修正 -│ ├── history.ts # 履歴制限（DM vs グループ） +│ ├── cache-ttl.ts # コンテキスト枝刈り用のキャッシュTTL追跡 +│ ├── compact.ts # 手動/自動Compactionロジック +│ ├── extensions.ts # 組み込み実行向けpi拡張の読み込み +│ ├── extra-params.ts # プロバイダー固有のストリームパラメーター +│ ├── google.ts # Google/Geminiのターン順序修正 +│ ├── history.ts # 履歴制限（DM対グループ） │ ├── lanes.ts # セッション/グローバルコマンドレーン -│ ├── logger.ts # サブシステム logger -│ ├── model.ts # ModelRegistry 経由のモデル解決 -│ ├── runs.ts # アクティブ実行追跡、中断、キュー -│ ├── sandbox-info.ts # システムプロンプト用 sandbox 情報 -│ ├── session-manager-cache.ts # SessionManager インスタンスキャッシュ +│ ├── logger.ts # サブシステムロガー +│ ├── model.ts # ModelRegistry経由のモデル解決 +│ ├── runs.ts # アクティブな実行の追跡、中断、キュー +│ ├── sandbox-info.ts # システムプロンプト用sandbox情報 +│ ├── session-manager-cache.ts # SessionManagerインスタンスのキャッシュ │ ├── session-manager-init.ts # セッションファイル初期化 │ ├── system-prompt.ts # システムプロンプトビルダー -│ ├── tool-split.ts # tool を builtIn と custom に分割 -│ ├── types.ts # EmbeddedPiAgentMeta, EmbeddedPiRunResult -│ └── utils.ts # ThinkLevel マッピング、エラー説明 -├── pi-embedded-subscribe.ts # セッションイベント購読/dispatch +│ ├── tool-split.ts # ツールを builtIn と custom に分割 +│ ├── types.ts # EmbeddedPiAgentMeta、EmbeddedPiRunResult +│ └── utils.ts # ThinkLevelマッピング、エラー説明 +├── pi-embedded-subscribe.ts # セッションイベントの購読/ディスパッチ ├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams ├── pi-embedded-subscribe.handlers.ts # イベントハンドラーファクトリー ├── pi-embedded-subscribe.handlers.lifecycle.ts ├── pi-embedded-subscribe.handlers.types.ts -├── pi-embedded-block-chunker.ts # ストリーミングブロック返信の分割 -├── pi-embedded-messaging.ts # Messaging tool の送信追跡 +├── pi-embedded-block-chunker.ts # ストリーミングブロック返信のチャンク化 +├── pi-embedded-messaging.ts # メッセージングツールの送信追跡 ├── pi-embedded-helpers.ts # エラー分類、ターン検証 ├── pi-embedded-helpers/ # ヘルパーモジュール -├── pi-embedded-utils.ts # 整形ユーティリティ +├── pi-embedded-utils.ts # フォーマットユーティリティ ├── pi-tools.ts # createOpenClawCodingTools() -├── pi-tools.abort.ts # tools 用 AbortSignal ラップ -├── pi-tools.policy.ts # tool allowlist/denylist ポリシー -├── pi-tools.read.ts # Read tool カスタマイズ -├── pi-tools.schema.ts # tool schema 正規化 +├── pi-tools.abort.ts # ツール向けAbortSignalラッピング +├── pi-tools.policy.ts # ツール許可/拒否ポリシー +├── pi-tools.read.ts # readツールのカスタマイズ +├── pi-tools.schema.ts # ツールスキーマ正規化 ├── pi-tools.types.ts # AnyAgentTool 型エイリアス ├── pi-tool-definition-adapter.ts # AgentTool -> ToolDefinition アダプター -├── pi-settings.ts # 設定上書き -├── pi-hooks/ # カスタム pi フック -│ ├── compaction-safeguard.ts # Safeguard extension +├── pi-settings.ts # 設定オーバーライド +├── pi-hooks/ # カスタムpiフック +│ ├── compaction-safeguard.ts # セーフガード拡張 │ ├── compaction-safeguard-runtime.ts -│ ├── context-pruning.ts # キャッシュ TTL コンテキスト pruning extension +│ ├── context-pruning.ts # キャッシュTTLコンテキスト枝刈り拡張 │ └── context-pruning/ -├── model-auth.ts # Auth profile 解決 -├── auth-profiles.ts # Profile ストア、cooldown、failover +├── model-auth.ts # 認証プロファイル解決 +├── auth-profiles.ts # プロファイルストア、クールダウン、フェイルオーバー ├── model-selection.ts # デフォルトモデル解決 -├── models-config.ts # models.json 生成 +├── models-config.ts # models.json生成 ├── model-catalog.ts # モデルカタログキャッシュ ├── context-window-guard.ts # コンテキストウィンドウ検証 ├── failover-error.ts # FailoverError クラス -├── defaults.ts # DEFAULT_PROVIDER, DEFAULT_MODEL +├── defaults.ts # DEFAULT_PROVIDER、DEFAULT_MODEL ├── system-prompt.ts # buildAgentSystemPrompt() ├── system-prompt-params.ts # システムプロンプトパラメーター解決 ├── system-prompt-report.ts # デバッグレポート生成 -├── tool-summaries.ts # tool 説明サマリー -├── tool-policy.ts # tool ポリシー解決 +├── tool-summaries.ts # ツール説明サマリー +├── tool-policy.ts # ツールポリシー解決 ├── transcript-policy.ts # トランスクリプト検証ポリシー -├── skills.ts # Skill スナップショット/プロンプト構築 -├── skills/ # Skill サブシステム -├── sandbox.ts # sandbox コンテキスト解決 -├── sandbox/ # sandbox サブシステム -├── channel-tools.ts # チャネル固有 tool 注入 -├── openclaw-tools.ts # OpenClaw 固有 tools -├── bash-tools.ts # exec/process tools -├── apply-patch.ts # apply_patch tool（OpenAI） -├── tools/ # 個別 tool 実装 +├── skills.ts # Skillsスナップショット/プロンプト構築 +├── skills/ # Skillsサブシステム +├── sandbox.ts # sandboxコンテキスト解決 +├── sandbox/ # sandboxサブシステム +├── channel-tools.ts # チャネル固有ツール注入 +├── openclaw-tools.ts # OpenClaw固有ツール +├── bash-tools.ts # exec/processツール +├── apply-patch.ts # apply_patch ツール（OpenAI） +├── tools/ # 個別ツール実装 │ ├── browser-tool.ts │ ├── canvas-tool.ts │ ├── cron-tool.ts @@ -134,19 +134,18 @@ src/agents/ └── ... ``` -チャネル固有のメッセージアクションランタイムは、現在 `src/agents/tools` 配下ではなく、Plugin が所有する extension -ディレクトリにあります。たとえば: +チャネル固有のメッセージアクションランタイムは、現在では `src/agents/tools` 配下ではなく、Plugin所有の拡張ディレクトリ配下に配置されています。たとえば次のようなものです。 -- Discord Plugin の action runtime ファイル -- Slack Plugin の action runtime ファイル -- Telegram Plugin の action runtime ファイル -- WhatsApp Plugin の action runtime ファイル +- Discord Pluginアクションランタイムファイル +- Slack Pluginアクションランタイムファイル +- Telegram Pluginアクションランタイムファイル +- WhatsApp Pluginアクションランタイムファイル -## 中核統合フロー +## コア統合フロー -### 1. 埋め込みエージェントの実行 +### 1. 組み込みエージェントの実行 -メインエントリーポイントは `pi-embedded-runner/run.ts` の `runEmbeddedPiAgent()` です。 +メインのエントリポイントは、`pi-embedded-runner/run.ts` 内の `runEmbeddedPiAgent()` です。 ```typescript import { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js"; @@ -170,7 +169,7 @@ const result = await runEmbeddedPiAgent({ ### 2. セッション作成 -`runEmbeddedAttempt()`（`runEmbeddedPiAgent()` から呼ばれる）内では、pi SDK が使われます。 +`runEmbeddedAttempt()`（`runEmbeddedPiAgent()` から呼び出される）の内部では、pi SDKが使用されます。 ```typescript import { @@ -207,7 +206,7 @@ applySystemPromptOverrideToSession(session, systemPromptOverride); ### 3. イベント購読 -`subscribeEmbeddedPiSession()` は、pi の `AgentSession` イベントを購読します。 +`subscribeEmbeddedPiSession()` は、piの `AgentSession` イベントを購読します。 ```typescript const subscription = subscribeEmbeddedPiSession({ @@ -224,9 +223,9 @@ const subscription = subscribeEmbeddedPiSession({ }); ``` -処理されるイベントには次が含まれます。 +処理されるイベントには次のものがあります。 -- `message_start` / `message_end` / `message_update`（ストリーミングテキスト/Thinking） +- `message_start` / `message_end` / `message_update`（ストリーミングテキスト/思考） - `tool_execution_start` / `tool_execution_update` / `tool_execution_end` - `turn_start` / `turn_end` - `agent_start` / `agent_end` @@ -240,27 +239,25 @@ const subscription = subscribeEmbeddedPiSession({ await session.prompt(effectivePrompt, { images: imageResult.images }); ``` -SDK は、LLM への送信、tool call の実行、応答のストリーミングを含む完全なエージェントループを処理します。 +SDKが完全なエージェントループを処理します。つまり、LLMへの送信、ツール呼び出しの実行、レスポンスのストリーミングを担当します。 -画像注入は prompt ローカルです。OpenClaw は現在の prompt から画像参照を読み込み、 -そのターンに対してのみ `images` 経由で渡します。古い履歴ターンを再走査して -画像ペイロードを再注入することはありません。 +画像注入はプロンプトローカルです。OpenClawは現在のプロンプトから画像参照を読み込み、そのターンに対してのみ `images` 経由で渡します。過去の履歴ターンを再スキャンして画像ペイロードを再注入することはありません。 -## Tool アーキテクチャ +## ツールアーキテクチャ -### Tool パイプライン +### ツールパイプライン -1. **ベース tools**: pi の `codingTools`（read, bash, edit, write） -2. **カスタム置き換え**: OpenClaw は bash を `exec`/`process` に置き換え、read/edit/write を sandbox 向けにカスタマイズ -3. **OpenClaw tools**: messaging, browser, canvas, sessions, Cron, Gateway など -4. **チャネル tools**: Discord/Telegram/Slack/WhatsApp 固有の action tools -5. **ポリシーフィルタリング**: tools は profile、プロバイダー、エージェント、グループ、sandbox ポリシーでフィルタされる -6. **Schema 正規化**: schema は Gemini/OpenAI の癖に合わせてクリーニングされる -7. **AbortSignal ラップ**: tools は abort signal を尊重するようラップされる +1. **ベースツール**: piの `codingTools`（read、bash、edit、write） +2. **カスタム置き換え**: OpenClawはbashを `exec`/`process` で置き換え、sandbox向けにread/edit/writeをカスタマイズ +3. **OpenClawツール**: メッセージング、ブラウザー、canvas、セッション、Cron、Gatewayなど +4. **チャネルツール**: Discord/Telegram/Slack/WhatsApp固有のアクションツール +5. **ポリシーフィルタリング**: プロファイル、プロバイダー、エージェント、グループ、sandboxポリシーによってツールをフィルタリング +6. **スキーマ正規化**: Gemini/OpenAI特有の癖に合わせてスキーマを整形 +7. **AbortSignalラッピング**: ツールをラップして中断シグナルを尊重するようにする -### Tool Definition アダプター +### ツール定義アダプター -pi-agent-core の `AgentTool` は、pi-coding-agent の `ToolDefinition` とは異なる `execute` シグネチャを持ちます。`pi-tool-definition-adapter.ts` 内のアダプターがこれを橋渡しします。 +pi-agent-coreの `AgentTool` は、pi-coding-agentの `ToolDefinition` とは異なる `execute` シグネチャを持っています。`pi-tool-definition-adapter.ts` 内のアダプターがこれを橋渡しします。 ```typescript export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { @@ -277,26 +274,26 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { } ``` -### Tool 分割戦略 +### ツール分割戦略 -`splitSdkTools()` は、すべての tools を `customTools` 経由で渡します。 +`splitSdkTools()` は、すべてのツールを `customTools` 経由で渡します。 ```typescript export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) { return { - builtInTools: [], // 空。すべて上書きする + builtInTools: [], // 空。すべてオーバーライドする customTools: toToolDefinitions(options.tools), }; } ``` -これにより、OpenClaw のポリシーフィルタリング、sandbox 統合、拡張 toolset が、プロバイダーをまたいで一貫して維持されます。 +これにより、OpenClawのポリシーフィルタリング、sandbox統合、拡張ツールセットが、プロバイダー間で一貫した状態に保たれます。 ## システムプロンプト構築 -システムプロンプトは `buildAgentSystemPrompt()`（`system-prompt.ts`）で構築されます。Tooling、Tool Call Style、安全ガードレール、OpenClaw CLI リファレンス、Skills、Docs、Workspace、Sandbox、Messaging、Reply Tags、Voice、Silent Replies、Heartbeats、Runtime metadata に加え、有効な場合は Memory と Reactions、さらに任意の context ファイルと追加システムプロンプト内容を含む完全なプロンプトを組み立てます。セクションは、サブエージェントで使われる最小プロンプトモード向けに切り詰められます。 +システムプロンプトは、`buildAgentSystemPrompt()`（`system-prompt.ts`）で構築されます。Tooling、Tool Call Style、安全ガードレール、OpenClaw CLIリファレンス、Skills、Docs、Workspace、Sandbox、Messaging、Reply Tags、Voice、Silent Replies、Heartbeats、ランタイムメタデータに加え、有効な場合はMemoryとReactions、さらに任意のコンテキストファイルや追加のシステムプロンプト内容を含む各セクションを組み立てます。サブエージェントで使用される最小プロンプトモードでは、セクションはトリミングされます。 -プロンプトはセッション作成後に `applySystemPromptOverrideToSession()` 経由で適用されます。 +プロンプトは、セッション作成後に `applySystemPromptOverrideToSession()` を通じて適用されます。 ```typescript const systemPromptOverride = createSystemPromptOverride(appendPrompt); @@ -307,17 +304,17 @@ applySystemPromptOverrideToSession(session, systemPromptOverride); ### セッションファイル -セッションは tree 構造（`id`/`parentId` リンク）を持つ JSONL ファイルです。pi の `SessionManager` が永続化を処理します。 +セッションは、ツリー構造（`id`/`parentId` のリンク）を持つJSONLファイルです。piの `SessionManager` が永続化を処理します。 ```typescript const sessionManager = SessionManager.open(params.sessionFile); ``` -OpenClaw はこれを `guardSessionManager()` でラップし、tool result の安全性を追加します。 +OpenClawはこれを `guardSessionManager()` でラップし、ツール結果の安全性を確保します。 ### セッションキャッシュ -`session-manager-cache.ts` は、ファイル解析の繰り返しを避けるために SessionManager インスタンスをキャッシュします。 +`session-manager-cache.ts` は、ファイルの再解析を避けるためにSessionManagerインスタンスをキャッシュします。 ```typescript await prewarmSessionFile(params.sessionFile); @@ -327,16 +324,11 @@ trackSessionManagerAccess(params.sessionFile); ### 履歴制限 -`limitHistoryTurns()` は、チャネル種別（DM vs グループ）に応じて会話履歴を削減します。 +`limitHistoryTurns()` は、チャネル種別（DMまたはグループ）に基づいて会話履歴をトリミングします。 ### Compaction -自動 Compaction はコンテキストオーバーフロー時に発動します。一般的なオーバーフローシグネチャには -`request_too_large`、`context length exceeded`、`input exceeds the -maximum number of tokens`、`input token count exceeds the maximum number of -input tokens`、`input is too long for the model`、`ollama error: context -length exceeded` があります。`compactEmbeddedPiSessionDirect()` は手動 -Compaction を処理します。 +自動Compactionは、コンテキストオーバーフロー時にトリガーされます。よくあるオーバーフローシグネチャには、`request_too_large`、`context length exceeded`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model`、`ollama error: context length exceeded` などがあります。`compactEmbeddedPiSessionDirect()` は手動Compactionを処理します。 ```typescript const compactResult = await compactEmbeddedPiSessionDirect({ @@ -346,16 +338,16 @@ const compactResult = await compactEmbeddedPiSessionDirect({ ## 認証とモデル解決 -### Auth profile +### 認証プロファイル -OpenClaw は、プロバイダーごとに複数の API キーを持つ auth profile ストアを維持します。 +OpenClawは、プロバイダーごとに複数のAPIキーを持つ認証プロファイルストアを維持します。 ```typescript const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false }); const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile }); ``` -profile は、cooldown 追跡付きで失敗時にローテーションします。 +プロファイルは、クールダウン追跡付きで障害時にローテーションされます。 ```typescript await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir }); @@ -374,13 +366,13 @@ const { model, error, authStorage, modelRegistry } = resolveModel( config, ); -// pi の ModelRegistry と AuthStorage を使用 +// piの ModelRegistry と AuthStorage を使用 authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); ``` -### Failover +### フェイルオーバー -設定されている場合、`FailoverError` がモデルフォールバックを発動します。 +設定されている場合、`FailoverError` はモデルのフォールバックをトリガーします。 ```typescript if (fallbackConfigured && isFailoverErrorMessage(errorText)) { @@ -394,13 +386,13 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) { } ``` -## Pi extension +## Pi拡張 -OpenClaw は、特化した動作のためにカスタム pi extension を読み込みます。 +OpenClawは、特殊な動作のためにカスタムPi拡張を読み込みます。 ### Compaction Safeguard -`src/agents/pi-hooks/compaction-safeguard.ts` は、適応的トークン予算と tool failure および file operation サマリーを含む Compaction ガードレールを追加します。 +`src/agents/pi-hooks/compaction-safeguard.ts` は、適応的なトークン予算編成に加え、ツール障害およびファイル操作の要約を含むガードレールをCompactionに追加します。 ```typescript if (resolveCompactionMode(params.cfg) === "safeguard") { @@ -409,9 +401,9 @@ if (resolveCompactionMode(params.cfg) === "safeguard") { } ``` -### Context Pruning +### コンテキスト枝刈り -`src/agents/pi-hooks/context-pruning.ts` は、キャッシュ TTL ベースの context pruning を実装します。 +`src/agents/pi-hooks/context-pruning.ts` は、キャッシュTTLベースのコンテキスト枝刈りを実装します。 ```typescript if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { @@ -427,51 +419,51 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { ## ストリーミングとブロック返信 -### ブロック分割 +### ブロックチャンク化 -`EmbeddedBlockChunker` は、ストリーミングテキストを離散的な返信ブロックに管理します。 +`EmbeddedBlockChunker` は、ストリーミングテキストを個別の返信ブロックに分割して管理します。 ```typescript const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null; ``` -### Thinking/Final タグ除去 +### 思考/最終タグの除去 -ストリーミング出力は、``/`` ブロックを取り除き、`` 内容を抽出するよう処理されます。 +ストリーミング出力は、``/`` ブロックを除去し、`` の内容を抽出するために処理されます。 ```typescript const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => { // ... の内容を除去 - // enforceFinalTag が有効なら、... の内容だけを返す + // enforceFinalTag の場合は、... の内容のみ返す }; ``` -### 返信 directive +### 返信ディレクティブ -`[[media:url]]`、`[[voice]]`、`[[reply:id]]` のような返信 directive は解析・抽出されます。 +`[[media:url]]`、`[[voice]]`、`[[reply:id]]` のような返信ディレクティブは解析され、抽出されます。 ```typescript const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk); ``` -## エラー処理 +## エラーハンドリング ### エラー分類 -`pi-embedded-helpers.ts` は、適切な処理のためにエラーを分類します。 +`pi-embedded-helpers.ts` は、適切に処理するためにエラーを分類します。 ```typescript isContextOverflowError(errorText) // コンテキストが大きすぎる -isCompactionFailureError(errorText) // Compaction に失敗 -isAuthAssistantError(lastAssistant) // Auth 失敗 +isCompactionFailureError(errorText) // Compactionに失敗した +isAuthAssistantError(lastAssistant) // 認証失敗 isRateLimitAssistantError(...) // レート制限 -isFailoverAssistantError(...) // Failover すべき +isFailoverAssistantError(...) // フェイルオーバーすべき classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ... ``` -### Thinking level フォールバック +### Thinking Levelフォールバック -thinking level がサポートされていない場合、フォールバックします。 +Thinking Levelがサポートされていない場合は、フォールバックします。 ```typescript const fallbackThinking = pickFallbackThinkingLevel({ @@ -484,9 +476,9 @@ if (fallbackThinking) { } ``` -## Sandbox 統合 +## sandbox統合 -sandbox mode が有効な場合、tools とパスは制約されます。 +sandboxモードが有効な場合、ツールとパスは制約されます。 ```typescript const sandbox = await resolveSandboxContext({ @@ -496,65 +488,65 @@ const sandbox = await resolveSandboxContext({ }); if (sandboxRoot) { - // sandbox 化された read/edit/write tools を使う - // Exec は container 内で実行 - // Browser は bridge URL を使う + // sandbox化された read/edit/write ツールを使用 + // Exec はコンテナー内で実行 + // Browser はブリッジURLを使用 } ``` -## プロバイダー固有処理 +## プロバイダー固有の処理 ### Anthropic -- refusal magic string の除去 -- 連続 role に対するターン検証 -- 厳格な upstream Pi tool パラメーター検証 +- 拒否マジック文字列の除去 +- 連続するロールに対するターン検証 +- 厳格なアップストリームPiツールパラメーター検証 ### Google/Gemini -- Plugin 所有の tool schema サニタイズ +- Plugin所有のツールスキーマサニタイズ ### OpenAI -- Codex モデル用の `apply_patch` tool -- thinking level のダウングレード処理 +- Codexモデル向け `apply_patch` ツール +- Thinking Levelダウングレード処理 -## TUI 統合 +## TUI統合 -OpenClaw には、pi-tui コンポーネントを直接使うローカル TUI モードもあります。 +OpenClawには、pi-tuiコンポーネントを直接使用するローカルTUIモードもあります。 ```typescript // src/tui/tui.ts import { ... } from "@mariozechner/pi-tui"; ``` -これにより、pi のネイティブモードに近い対話型ターミナル体験が提供されます。 +これにより、piのネイティブモードに似た対話型ターミナル体験が提供されます。 -## Pi CLI との主な違い +## Pi CLIとの主な違い -| 観点 | Pi CLI | OpenClaw Embedded | -| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------- | -| 起動方法 | `pi` コマンド / RPC | `createAgentSession()` 経由の SDK | -| Tools | デフォルト coding tools | カスタム OpenClaw tool スイート | -| システムプロンプト | AGENTS.md + prompts | チャネル/コンテキストごとの動的生成 | -| セッション保存 | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/`（または `$OPENCLAW_STATE_DIR/agents//sessions/`） | -| Auth | 単一認証情報 | ローテーション付きマルチ profile | -| Extensions | ディスクから読み込み | プログラム的 + ディスクパス | -| イベント処理 | TUI レンダリング | コールバックベース（`onBlockReply` など） | +| 項目 | Pi CLI | OpenClaw Embedded | +| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| 呼び出し | `pi` コマンド / RPC | `createAgentSession()` 経由のSDK | +| ツール | デフォルトのコーディングツール | カスタムOpenClawツールスイート | +| システムプロンプト | AGENTS.md + プロンプト | チャネル/コンテキストごとに動的 | +| セッション保存 | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/`（または `$OPENCLAW_STATE_DIR/agents//sessions/`） | +| 認証 | 単一の資格情報 | ローテーション付きマルチプロファイル | +| 拡張 | ディスクから読み込み | プログラム的指定 + ディスクパス | +| イベント処理 | TUIレンダリング | コールバックベース（`onBlockReply` など） | -## 今後の考慮事項 +## 今後の検討事項 -将来的に見直しうる領域: +再設計の候補となる領域は次のとおりです。 -1. **Tool シグネチャ整合**: 現在は pi-agent-core と pi-coding-agent のシグネチャ差をアダプトしている -2. **Session manager ラップ**: `guardSessionManager` は安全性を加えるが複雑さも増す -3. **Extension 読み込み**: pi の `ResourceLoader` をより直接使える可能性がある -4. **ストリーミングハンドラーの複雑化**: `subscribeEmbeddedPiSession` が大きくなってきている -5. **プロバイダー固有の癖**: 多くのプロバイダー固有コードパスがあり、pi 側で処理できる可能性がある +1. **ツールシグネチャの整合**: 現在はpi-agent-coreとpi-coding-agentのシグネチャ間を適応している +2. **SessionManagerラッピング**: `guardSessionManager` は安全性を追加するが、複雑さも増す +3. **拡張読み込み**: piの `ResourceLoader` をより直接的に使用できる可能性がある +4. **ストリーミングハンドラーの複雑さ**: `subscribeEmbeddedPiSession` が大きくなってきている +5. **プロバイダー固有の癖**: pi側で処理できる可能性のあるプロバイダー固有コードパスが多い ## テスト -Pi 統合のカバレッジは次のスイートにまたがります。 +Pi統合のカバレッジは、以下のスイートにまたがっています。 - `src/agents/pi-*.test.ts` - `src/agents/pi-auth-json.test.ts` diff --git a/docs/ja-JP/providers/deepseek.md b/docs/ja-JP/providers/deepseek.md index ee5034e2c..31612896c 100644 --- a/docs/ja-JP/providers/deepseek.md +++ b/docs/ja-JP/providers/deepseek.md @@ -1,42 +1,42 @@ --- read_when: - - OpenClawでDeepSeekを使いたい場合 - - API keyのenv varまたはCLI auth choiceが必要な場合 -summary: DeepSeekのセットアップ（auth + model選択） + - OpenClaw で DeepSeek を使いたい場合 + - API キーの環境変数または CLI の認証オプションが必要です +summary: DeepSeek のセットアップ（認証 + モデル選択） title: DeepSeek x-i18n: - generated_at: "2026-04-24T05:14:29Z" + generated_at: "2026-04-24T15:21:31Z" model: gpt-5.4 provider: openai - source_hash: ead407c67c05bd8700db1cba36defdd9d47bdc9a071c76a07c4b4fb82f6b80e2 + source_hash: 5b0d2345c72328e14351d71c5784204dc6ed9dc922f919b6adfac394001c3261 source_path: providers/deepseek.md workflow: 15 --- -[DeepSeek](https://www.deepseek.com) は、OpenAI互換APIを持つ強力なAIモデルを提供します。 +[DeepSeek](https://www.deepseek.com) は、OpenAI互換APIを備えた高性能なAIモデルを提供しています。 -| Property | Value | +| プロパティ | 値 | | -------- | -------------------------- | -| Provider | `deepseek` | -| Auth | `DEEPSEEK_API_KEY` | +| プロバイダー | `deepseek` | +| 認証 | `DEEPSEEK_API_KEY` | | API | OpenAI互換 | | Base URL | `https://api.deepseek.com` | ## はじめに - - [platform.deepseek.com](https://platform.deepseek.com/api_keys) でAPI keyを作成してください。 + + [platform.deepseek.com](https://platform.deepseek.com/api_keys) でAPI キーを作成します。 - + ```bash openclaw onboard --auth-choice deepseek-api-key ``` - これによりAPI keyの入力を求められ、デフォルトmodelとして `deepseek/deepseek-chat` が設定されます。 + API キーの入力を求められ、`deepseek/deepseek-v4-flash` がデフォルトモデルとして設定されます。 - + ```bash openclaw models list --provider deepseek ``` @@ -44,8 +44,8 @@ x-i18n: - - スクリプト化またはheadlessなインストールでは、すべてのflagを直接渡してください: + + スクリプト化されたインストールやヘッドレス環境でのインストールでは、すべてのフラグを直接渡します。 ```bash openclaw onboard --non-interactive \ @@ -60,30 +60,32 @@ x-i18n: -Gatewayがdaemon（launchd/systemd）として動作する場合、`DEEPSEEK_API_KEY` -がそのprocessで利用可能であることを確認してください（たとえば `~/.openclaw/.env` や +Gateway がデーモン（launchd/systemd）として実行される場合は、`DEEPSEEK_API_KEY` +がそのプロセスで利用可能であることを確認してください（たとえば、`~/.openclaw/.env` または `env.shellEnv` 経由）。 -## 組み込みcatalog +## 組み込みカタログ -| Model ref | Name | Input | Context | Max output | 注記 | -| ---------------------------- | ----------------- | ----- | ------- | ---------- | -------------------------------------------------- | -| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | デフォルトmodel; DeepSeek V3.2のnon-thinkingサーフェス | -| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | reasoning有効なV3.2サーフェス | +| モデル参照 | 名前 | 入力 | コンテキスト | 最大出力 | 注記 | +| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ | +| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | デフォルトモデル; V4の思考対応サーフェス | +| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | V4の思考対応サーフェス | +| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2の非思考サーフェス | +| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 推論対応のV3.2サーフェス | -現在、両方の同梱modelはsource上でstreaming usage compatibilityを広告しています。 +V4モデルはDeepSeekの`thinking`制御をサポートしています。OpenClaw は、ツール呼び出しを含む思考セッションを継続できるように、フォローアップターンでDeepSeek の`reasoning_content`も再送します。 -## Config例 +## 設定例 ```json5 { env: { DEEPSEEK_API_KEY: "sk-..." }, agents: { defaults: { - model: { primary: "deepseek/deepseek-chat" }, + model: { primary: "deepseek/deepseek-v4-flash" }, }, }, } @@ -93,9 +95,9 @@ Gatewayがdaemon（launchd/systemd）として動作する場合、`DEEPSEEK_API - provider、model ref、failover動作の選び方。 + プロバイダー、モデル参照、フェイルオーバー動作の選び方。 - agent、model、provider向けの完全なconfigリファレンス。 + エージェント、モデル、プロバイダーの完全な設定リファレンス。 diff --git a/docs/ja-JP/tools/plugin.md b/docs/ja-JP/tools/plugin.md index 6090eaa70..4b7dabfc9 100644 --- a/docs/ja-JP/tools/plugin.md +++ b/docs/ja-JP/tools/plugin.md @@ -1,32 +1,36 @@ --- read_when: - - Pluginのインストールまたは設定 - - Pluginの検出と読み込みルールの理解 - - Codex/Claude互換Pluginバンドルの操作 + - プラグインのインストールまたは設定 + - プラグインの検出と読み込みルールを理解する + - Codex/Claude互換のプラグインバンドルを扱う sidebarTitle: Install and Configure -summary: OpenClaw Pluginのインストール、設定、および管理 -title: Plugin +summary: OpenClawのプラグインをインストール、設定、管理する +title: プラグイン x-i18n: - generated_at: "2026-04-24T09:03:05Z" + generated_at: "2026-04-24T15:21:34Z" model: gpt-5.4 provider: openai - source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28 + source_hash: 947bb7ffc13280fd63f79bb68cb18a37c6614144b91a83afd38e5ac3c5187aed source_path: tools/plugin.md workflow: 15 --- -Pluginは、OpenClawに新しい機能を追加します: チャンネル、モデルプロバイダー、エージェントハーネス、ツール、Skills、音声、realtime文字起こし、realtime音声、メディア理解、画像生成、動画生成、Web取得、Web検索などです。Pluginには、**core**（OpenClawに同梱）なものと、**external**（コミュニティがnpmで公開）なものがあります。 +プラグインは新しい機能でOpenClawを拡張します。たとえば、チャネル、モデルプロバイダー、 +エージェントハーネス、ツール、Skills、音声、リアルタイム文字起こし、リアルタイム +音声、メディア理解、画像生成、動画生成、Web取得、Web +検索などです。一部のプラグインは**コア**（OpenClawに同梱）で、その他は +**外部**（コミュニティによってnpmで公開）です。 ## クイックスタート - + ```bash openclaw plugins list ``` - + ```bash # npmから openclaw plugins install @openclaw/voice-call @@ -38,17 +42,17 @@ Pluginは、OpenClawに新しい機能を追加します: チャンネル、モ - + ```bash openclaw gateway restart ``` - その後、設定ファイルの `plugins.entries.\.config` 配下で設定します。 + その後、設定ファイルの `plugins.entries.\.config` で設定します。 -チャットネイティブな操作を好む場合は、`commands.plugins: true` を有効にして次を使います: +チャットネイティブな操作を使いたい場合は、`commands.plugins: true` を有効にして、次を使用します。 ```text /plugin install clawhub:@openclaw/voice-call @@ -56,31 +60,42 @@ Pluginは、OpenClawに新しい機能を追加します: チャンネル、モ /plugin enable voice-call ``` -インストールパスはCLIと同じリゾルバーを使用します: ローカルパス/アーカイブ、明示的な `clawhub:`、または裸のパッケージ指定（最初にClawHub、次にnpmへフォールバック）。 +インストールパスはCLIと同じリゾルバーを使用します。ローカルパス/アーカイブ、明示的な +`clawhub:`、または素のパッケージ指定（最初にClawHub、次にnpmへフォールバック）です。 -設定が無効な場合、通常はインストールは安全側で失敗し、`openclaw doctor --fix` を案内します。唯一の回復例外は、`openclaw.install.allowInvalidConfigRecovery` にオプトインしたPlugin向けの、狭いバンドル済みPlugin再インストールパスです。 +設定が無効な場合、通常はインストールは安全側で失敗し、 +`openclaw doctor --fix` を案内します。唯一の回復例外は、オプトインしているプラグイン向けの、 +同梱プラグインの限定的な再インストール経路です。 +`openclaw.install.allowInvalidConfigRecovery`。 -パッケージ化されたOpenClawインストールでは、すべてのバンドル済みPluginのランタイム依存ツリーを事前に積極インストールしません。バンドル済みのOpenClaw所有Pluginが、Plugin設定、従来のチャンネル設定、またはデフォルト有効マニフェストから有効になっている場合、起動時の修復では、そのPluginが宣言したランタイム依存関係のみをimport前に修復します。外部Pluginとカスタム読み込みパスは、引き続き `openclaw plugins install` でインストールする必要があります。 +パッケージ化されたOpenClawインストールでは、同梱されたすべてのプラグインの +ランタイム依存ツリーを事前にすべてインストールしません。 +OpenClaw所有の同梱プラグインが、プラグイン設定、レガシーチャネル設定、 +またはデフォルトで有効なマニフェストからアクティブな場合、起動時の +修復では、そのプラグインをインポートする前に、そのプラグインが宣言した +ランタイム依存関係だけを修復します。 +外部プラグインおよびカスタム読み込みパスは、引き続き +`openclaw plugins install` でインストールする必要があります。 -## Pluginの種類 +## プラグインの種類 -OpenClawは2つのPlugin形式を認識します: +OpenClawは2つのプラグイン形式を認識します。 -| Format | 仕組み | 例 | +| 形式 | 仕組み | 例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + ランタイムモジュール。インプロセスで実行される | 公式Plugin、コミュニティnpmパッケージ | -| **Bundle** | Codex/Claude/Cursor互換レイアウト。OpenClaw機能へマップされる | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Native** | `openclaw.plugin.json` + ランタイムモジュール。インプロセスで実行される | 公式プラグイン、コミュニティのnpmパッケージ | +| **Bundle** | Codex/Claude/Cursor互換レイアウト。OpenClawの機能にマッピングされる | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -どちらも `openclaw plugins list` に表示されます。Bundleの詳細は [Plugin Bundles](/ja-JP/plugins/bundles) を参照してください。 +どちらも `openclaw plugins list` に表示されます。バンドルの詳細は [プラグインバンドル](/ja-JP/plugins/bundles) を参照してください。 -ネイティブPluginを書いている場合は、[Building Plugins](/ja-JP/plugins/building-plugins) +Nativeプラグインを作成する場合は、[プラグインの構築](/ja-JP/plugins/building-plugins) と [Plugin SDK Overview](/ja-JP/plugins/sdk-overview) から始めてください。 -## 公式Plugin +## 公式プラグイン ### インストール可能（npm） -| Plugin | Package | Docs | +| プラグイン | パッケージ | ドキュメント | | --------------- | ---------------------- | ------------------------------------ | | Matrix | `@openclaw/matrix` | [Matrix](/ja-JP/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/ja-JP/channels/msteams) | @@ -89,7 +104,7 @@ OpenClawは2つのPlugin形式を認識します: | Zalo | `@openclaw/zalo` | [Zalo](/ja-JP/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/ja-JP/plugins/zalouser) | -### core（OpenClawに同梱） +### コア（OpenClawに同梱） @@ -100,9 +115,9 @@ OpenClawは2つのPlugin形式を認識します: `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — バンドル済みメモリ検索（デフォルトは `plugins.slots.memory` 経由） - - `memory-lancedb` — 必要時インストールの長期メモリ。自動recall/capture付き（`plugins.slots.memory = "memory-lancedb"` を設定） + + - `memory-core` — 同梱のメモリ検索（`plugins.slots.memory` によるデフォルト） + - `memory-lancedb` — 自動リコール/キャプチャ付きのオンデマンドインストール長期メモリ（`plugins.slots.memory = "memory-lancedb"` を設定） @@ -110,12 +125,12 @@ OpenClawは2つのPlugin形式を認識します: - - `browser` — browserツール、`openclaw browser` CLI、`browser.request` Gatewayメソッド、browserランタイム、およびデフォルトbrowser controlサービス向けのバンドル済みbrowser Plugin（デフォルトで有効。置き換える前に無効化してください） + - `browser` — ブラウザツール、`openclaw browser` CLI、`browser.request` Gatewayメソッド、ブラウザランタイム、およびデフォルトのブラウザ制御サービス向けの同梱ブラウザプラグイン（デフォルトで有効。置き換える前に無効化してください） - `copilot-proxy` — VS Code Copilot Proxyブリッジ（デフォルトでは無効） -サードパーティPluginを探していますか？ [Community Plugins](/ja-JP/plugins/community) を参照してください。 +サードパーティ製プラグインを探していますか？ [コミュニティプラグイン](/ja-JP/plugins/community) を参照してください。 ## 設定 @@ -133,103 +148,141 @@ OpenClawは2つのPlugin形式を認識します: } ``` -| Field | 説明 | +| フィールド | 説明 | | ---------------- | --------------------------------------------------------- | -| `enabled` | マスタートグル（デフォルト: `true`） | -| `allow` | Plugin allowlist（任意） | -| `deny` | Plugin denylist（任意。denyが優先） | -| `load.paths` | 追加のPluginファイル/ディレクトリ | -| `slots` | 排他的スロット選択子（例: `memory`, `contextEngine`） | -| `entries.\` | Pluginごとのトグル + 設定 | +| `enabled` | マスタートグル（デフォルト: `true`） | +| `allow` | プラグインの許可リスト（任意） | +| `deny` | プラグインの拒否リスト（任意。拒否が優先） | +| `load.paths` | 追加のプラグインファイル/ディレクトリ | +| `slots` | 排他的スロットのセレクター（例: `memory`, `contextEngine`） | +| `entries.\` | プラグインごとのトグル + 設定 | -設定変更には**Gatewayの再起動が必要**です。Gatewayが設定監視 + インプロセス再起動有効状態（デフォルトの `openclaw gateway` パス）で動作している場合、その再起動は通常、設定書き込みの少し後に自動実行されます。 +設定の変更は**Gatewayの再起動が必要**です。Gatewayが設定監視と +インプロセス再起動を有効にして実行されている場合（デフォルトの `openclaw gateway` 経路）、 +通常、その再起動は設定の書き込みが反映された少し後に自動で実行されます。 +Nativeプラグインのランタイムコードやライフサイクル +フックに対する、サポートされたホットリロード経路はありません。更新された +`register(api)` コード、`api.on(...)` フック、ツール、サービス、または +プロバイダー/ランタイムフックが実行されることを期待する前に、 +ライブチャネルを提供しているGatewayプロセスを再起動してください。 - - - **Disabled**: Pluginは存在するが、有効化ルールによって無効化されています。設定は保持されます。 - - **Missing**: 設定がPlugin IDを参照しているが、検出で見つかりませんでした。 - - **Invalid**: Pluginは存在するが、その設定が宣言されたスキーマに一致しません。 +`openclaw plugins list` はローカルのCLI/設定スナップショットです。そこにある `loaded` プラグインは、 +そのCLI呼び出しで見えている設定/ファイルから、そのプラグインが検出可能かつ読み込み可能であることを意味します。 +しかし、それは、すでに実行中のリモートGateway子プロセスが +同じプラグインコードに再起動されたことの証明にはなりません。 +ラッパープロセスを使うVPS/コンテナ構成では、実際の +`openclaw gateway run` プロセスに再起動を送るか、 +実行中のGatewayに対して `openclaw gateway restart` を使用してください。 + + + - **無効**: プラグインは存在するが、有効化ルールによってオフになっている状態。設定は保持されます。 + - **欠落**: 設定がプラグインidを参照しているが、検出で見つからなかった状態。 + - **無効設定**: プラグインは存在するが、その設定が宣言されたスキーマに一致しない状態。 ## 検出と優先順位 -OpenClawは、次の順序でPluginをスキャンします（最初に一致したものが優先）: +OpenClawは次の順序でプラグインをスキャンします（最初に一致したものが優先）: - `plugins.load.paths` — 明示的なファイルまたはディレクトリパス。 + `plugins.load.paths` — 明示的なファイルまたはディレクトリのパス。 - + `\/.openclaw//*.ts` および `\/.openclaw//*/index.ts`。 - + `~/.openclaw//*.ts` および `~/.openclaw//*/index.ts`。 - - OpenClawに同梱されています。多くはデフォルトで有効です（モデルプロバイダー、音声など）。 + + OpenClawに同梱されています。多くはデフォルトで有効です（モデルプロバイダー、音声）。 その他は明示的な有効化が必要です。 ### 有効化ルール -- `plugins.enabled: false` はすべてのPluginを無効化します -- `plugins.deny` は常にallowより優先されます -- `plugins.entries.\.enabled: false` はそのPluginを無効化します -- ワークスペース由来のPluginは**デフォルトで無効**です（明示的に有効化する必要があります） -- バンドル済みPluginは、上書きされない限り組み込みのデフォルト有効セットに従います -- 排他的スロットは、そのスロットに選ばれたPluginを強制的に有効化することがあります -- 一部のバンドル済みオプトインPluginは、設定でプロバイダーのmodel ref、チャンネル設定、ハーネスランタイムなどのPlugin所有サーフェスが指定されると自動的に有効化されます -- OpenAI系のCodexルートは独立したPlugin境界を保ちます: - `openai-codex/*` はOpenAI Pluginに属し、一方でバンドル済みCodex - app-server Pluginは `embeddedHarness.runtime: "codex"` または従来の - `codex/*` model refs によって選択されます +- `plugins.enabled: false` はすべてのプラグインを無効化します +- `plugins.deny` は常に allow より優先されます +- `plugins.entries.\.enabled: false` はそのプラグインを無効化します +- ワークスペース由来のプラグインは**デフォルトで無効**です（明示的に有効化する必要があります） +- 同梱プラグインは、上書きされない限り、組み込みのデフォルト有効セットに従います +- 排他的スロットは、そのスロット用に選択されたプラグインを強制的に有効化できます +- 一部のオプトイン型同梱プラグインは、設定で + プラグイン所有サーフェス（プロバイダーモデル参照、チャネル設定、またはハーネス + ランタイムなど）が指定されると自動的に有効化されます +- OpenAIファミリーのCodexルートは、プラグイン境界を別々に保ちます: + `openai-codex/*` はOpenAIプラグインに属し、一方で同梱のCodex + app-serverプラグインは `embeddedHarness.runtime: "codex"` またはレガシーの + `codex/*` モデル参照で選択されます -## Pluginスロット（排他的カテゴリ） +## ランタイムフックのトラブルシューティング -一部のカテゴリは排他的です（一度に1つだけ有効）: +プラグインが `plugins list` には表示されるのに、`register(api)` の副作用やフックが +ライブチャットトラフィックで実行されない場合は、まず次を確認してください。 + +- `openclaw gateway status --deep --require-rpc` を実行し、アクティブな + Gateway URL、プロファイル、設定パス、プロセスが、いま編集しているものと一致していることを確認します。 +- プラグインのインストール/設定/コード変更後に、ライブGatewayを再起動します。ラッパー + コンテナでは、PID 1 は単なるスーパーバイザーである場合があります。その場合は子の + `openclaw gateway run` プロセスを再起動またはシグナル送信してください。 +- `openclaw plugins inspect --json` を使って、フック登録と + 診断を確認します。`llm_input`、 + `llm_output`、`agent_end` のような同梱以外の会話フックには、 + `plugins.entries..hooks.allowConversationAccess=true` が必要です。 +- モデル切り替えには、`before_model_resolve` を推奨します。これはエージェントターンの + モデル解決前に実行されます。`llm_output` は、モデル試行が + アシスタント出力を生成した後にしか実行されません。 +- 実際に有効なセッションモデルの証明には、`openclaw sessions` または + Gatewayのセッション/ステータスサーフェスを使用し、プロバイダーペイロードをデバッグする場合は、 + Gatewayを `--raw-stream --raw-stream-path ` 付きで起動してください。 + +## プラグインスロット（排他的カテゴリ） + +一部のカテゴリは排他的です（一度に1つだけアクティブ）: ```json5 { plugins: { slots: { - memory: "memory-core", // または "none" で無効化 - contextEngine: "legacy", // またはPlugin id + memory: "memory-core", // または無効化するには "none" + contextEngine: "legacy", // またはプラグインid }, }, } ``` -| Slot | 制御対象 | デフォルト | +| スロット | 制御対象 | デフォルト | | --------------- | --------------------- | ------------------- | -| `memory` | Active Memory Plugin | `memory-core` | +| `memory` | Active Memoryプラグイン | `memory-core` | | `contextEngine` | アクティブなコンテキストエンジン | `legacy`（組み込み） | ## CLIリファレンス ```bash openclaw plugins list # コンパクトな一覧 -openclaw plugins list --enabled # 読み込まれたPluginのみ -openclaw plugins list --verbose # Pluginごとの詳細行 +openclaw plugins list --enabled # 読み込まれたプラグインのみ +openclaw plugins list --verbose # プラグインごとの詳細行 openclaw plugins list --json # 機械可読な一覧 openclaw plugins inspect # 詳細情報 openclaw plugins inspect --json # 機械可読 -openclaw plugins inspect --all # 全体表 -openclaw plugins info # inspectの別名 +openclaw plugins inspect --all # フリート全体のテーブル +openclaw plugins info # inspectのエイリアス openclaw plugins doctor # 診断 openclaw plugins install # インストール（最初にClawHub、次にnpm） openclaw plugins install clawhub: # ClawHubのみからインストール -openclaw plugins install --force # 既存インストールを上書き +openclaw plugins install --force # 既存のインストールを上書き openclaw plugins install # ローカルパスからインストール openclaw plugins install -l # 開発用にリンク（コピーなし） openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # 解決された正確なnpm specを記録 +openclaw plugins install --pin # 解決された正確なnpm指定を記録 openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # 1つのPluginを更新 +openclaw plugins update # 1つのプラグインを更新 openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # すべて更新 openclaw plugins uninstall # 設定/インストール記録を削除 @@ -241,35 +294,66 @@ openclaw plugins enable openclaw plugins disable ``` -バンドル済みPluginはOpenClawに同梱されています。多くはデフォルトで有効です（たとえば -バンドル済みモデルプロバイダー、バンドル済み音声プロバイダー、バンドル済みbrowser -Plugin）。その他のバンドル済みPluginは、引き続き `openclaw plugins enable ` が必要です。 +同梱プラグインはOpenClawに同梱されています。多くはデフォルトで有効です（たとえば、 +同梱モデルプロバイダー、同梱音声プロバイダー、同梱browser +プラグインなど）。一方で、その他の同梱プラグインは依然として `openclaw plugins enable ` が必要です。 -`--force` は、既存のインストール済みPluginまたはフックパックをその場で上書きします。追跡中のnpm -Pluginの通常アップグレードには `openclaw plugins update ` を使用してください。これは `--link` ではサポートされません。`--link` は管理対象のインストール先へコピーせず、元のパスを再利用するためです。 +`--force` は、既存のインストール済みプラグインまたはフックパックをその場で上書きします。追跡対象のnpm +プラグインの日常的なアップグレードには +`openclaw plugins update ` を使用してください。これは +`--link` とは併用できません。`--link` は、管理対象のインストール先にコピーする代わりに、 +ソースパスを再利用するためです。 -`plugins.allow` がすでに設定されている場合、`openclaw plugins install` は、インストールした -Plugin IDをそのallowlistへ追加してから有効化するため、再起動後すぐに読み込み可能になります。 +`plugins.allow` がすでに設定されている場合、`openclaw plugins install` は +有効化する前に、インストールされたプラグインidをその許可リストに追加するため、 +再起動後すぐにインストールしたプラグインを読み込めます。 -`openclaw plugins update ` は追跡中のインストールに適用されます。dist-tagまたは正確なバージョン付きのnpmパッケージspecを渡すと、パッケージ名を追跡中Pluginレコードへ解決し直し、将来の更新用に新しいspecを記録します。バージョンなしのパッケージ名を渡すと、正確にpinされたインストールはレジストリのデフォルトリリースラインへ戻されます。インストール済みnpm Pluginが、解決されたバージョンと記録済みアーティファクトIDにすでに一致している場合、OpenClawはダウンロード、再インストール、設定書き換えを行わずに更新をスキップします。 +`openclaw plugins update ` は追跡対象のインストールに適用されます。 +dist-tagまたは厳密なバージョン付きのnpmパッケージ指定を渡すと、パッケージ名が +追跡対象のプラグインレコードに解決し直され、今後の更新用に新しい指定が記録されます。 +バージョンなしでパッケージ名を渡すと、厳密にpinされたインストールは +レジストリのデフォルトのリリースラインに戻ります。インストール済みのnpmプラグインが +すでに解決済みバージョンと記録済みアーティファクトIDに一致している場合、 +OpenClawはダウンロード、再インストール、設定の書き換えを行わずに更新をスキップします。 -`--pin` はnpm専用です。`--marketplace` ではサポートされません。marketplaceインストールはnpm specではなく、marketplaceソースメタデータを永続化するためです。 +`--pin` はnpm専用です。`--marketplace` とは併用できません。これは +マーケットプレイス経由のインストールでは、npm指定の代わりに +マーケットプレイスのソースメタデータが保持されるためです。 -`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる誤検知に対する緊急用オーバーライドです。これにより、組み込みの `critical` 所見を超えてPluginインストールとPlugin更新を継続できますが、それでもPluginの `before_install` ポリシーブロックやスキャン失敗によるブロックは回避しません。 +`--dangerously-force-unsafe-install` は、組み込みの危険コードスキャナーによる +誤検知に対する非常用の上書きオプションです。これにより、組み込みの `critical` +検出結果があってもプラグインのインストールと更新を続行できますが、それでも +プラグインの `before_install` ポリシーブロックやスキャン失敗によるブロックは回避しません。 -このCLIフラグは、Pluginのインストール/更新フローにのみ適用されます。GatewayバックのSkill依存関係インストールでは、代わりに対応する `dangerouslyForceUnsafeInstall` リクエストオーバーライドを使用します。一方、`openclaw skills install` は別個のClawHub Skillsダウンロード/インストールフローのままです。 +このCLIフラグは、プラグインのインストール/更新フローにのみ適用されます。Gatewayを使うSkillの +依存関係インストールでは、代わりに対応する +`dangerouslyForceUnsafeInstall` リクエストオーバーライドを使用します。一方、 +`openclaw skills install` は引き続き別個のClawHub +Skillダウンロード/インストールフローです。 -互換Bundleは、同じPluginの一覧表示/inspect/enable/disableフローに参加します。現在のランタイムサポートには、bundle Skills、Claude command-skills、Claude `settings.json` デフォルト、Claude `.lsp.json` とマニフェスト宣言の `lspServers` デフォルト、Cursor command-skills、および互換Codexフックディレクトリが含まれます。 +互換バンドルは、同じプラグインのlist/inspect/enable/disableフローに参加します。 +現在のランタイムサポートには、バンドルSkill、Claude command-skills、 +Claude `settings.json` のデフォルト、Claude `.lsp.json` および +manifestで宣言された `lspServers` のデフォルト、Cursor command-skills、 +互換性のあるCodexフックディレクトリが含まれます。 -`openclaw plugins inspect ` は、bundleバックPlugin向けに、検出されたbundle機能に加えて、サポートされる/サポートされないMCPおよびLSPサーバーエントリも報告します。 +`openclaw plugins inspect ` は、検出されたバンドル機能に加えて、 +バンドルベースのプラグインに対してサポートされる、またはサポートされないMCPおよびLSPサーバー項目も報告します。 -Marketplaceソースには、`~/.claude/plugins/known_marketplaces.json` にあるClaudeの既知marketplace名、ローカルmarketplaceルートまたは `marketplace.json` パス、`owner/repo` のようなGitHub省略記法、GitHubリポジトリURL、またはgit URLを使用できます。リモートmarketplaceでは、Pluginエントリはクローンしたmarketplaceリポジトリ内にとどまり、相対パスソースのみを使用する必要があります。 +マーケットプレイスのソースには、 +`~/.claude/plugins/known_marketplaces.json` にあるClaude既知マーケットプレイス名、 +ローカルのマーケットプレイスルートまたは `marketplace.json` パス、 +`owner/repo` のようなGitHub省略記法、GitHubリポジトリURL、またはgit URLを指定できます。 +リモートマーケットプレイスでは、プラグインエントリはクローンされた +マーケットプレイスリポジトリ内にとどまり、相対パスのソースのみを使用する必要があります。 -完全な詳細は [`openclaw plugins` CLIリファレンス](/ja-JP/cli/plugins) を参照してください。 +詳細は [`openclaw plugins` CLIリファレンス](/ja-JP/cli/plugins) を参照してください。 -## Plugin API概要 +## プラグインAPI概要 -ネイティブPluginは、`register(api)` を公開するエントリオブジェクトをexportします。古いPluginはまだ従来の別名として `activate(api)` を使うことがありますが、新しいPluginは `register` を使うべきです。 +Nativeプラグインは、`register(api)` を公開するエントリオブジェクトをエクスポートします。古い +プラグインでは、レガシーエイリアスとして `activate(api)` をまだ使用している場合がありますが、 +新しいプラグインは `register` を使用するべきです。 ```typescript export default definePluginEntry({ @@ -289,46 +373,50 @@ export default definePluginEntry({ }); ``` -OpenClawはエントリオブジェクトを読み込み、Plugin有効化時に `register(api)` を呼び出します。ローダーは古いPlugin向けに引き続き `activate(api)` へフォールバックしますが、バンドル済みPluginと新しい外部Pluginでは、`register` を公開契約として扱うべきです。 +OpenClawはエントリオブジェクトを読み込み、プラグインの +アクティベーション中に `register(api)` を呼び出します。ローダーは古いプラグイン向けに +引き続き `activate(api)` にフォールバックしますが、 +同梱プラグインと新しい外部プラグインでは `register` を +公開契約として扱うべきです。 一般的な登録メソッド: -| Method | 登録するもの | +| メソッド | 登録するもの | | --------------------------------------- | --------------------------- | -| `registerProvider` | モデルプロバイダー（LLM） | -| `registerChannel` | チャットチャンネル | -| `registerTool` | エージェントツール | -| `registerHook` / `on(...)` | ライフサイクルフック | -| `registerSpeechProvider` | テキスト読み上げ / STT | -| `registerRealtimeTranscriptionProvider` | ストリーミングSTT | -| `registerRealtimeVoiceProvider` | 双方向realtime音声 | -| `registerMediaUnderstandingProvider` | 画像/音声解析 | -| `registerImageGenerationProvider` | 画像生成 | -| `registerMusicGenerationProvider` | 音楽生成 | -| `registerVideoGenerationProvider` | 動画生成 | +| `registerProvider` | モデルプロバイダー（LLM） | +| `registerChannel` | チャットチャネル | +| `registerTool` | エージェントツール | +| `registerHook` / `on(...)` | ライフサイクルフック | +| `registerSpeechProvider` | Text-to-speech / STT | +| `registerRealtimeTranscriptionProvider` | ストリーミングSTT | +| `registerRealtimeVoiceProvider` | 双方向リアルタイム音声 | +| `registerMediaUnderstandingProvider` | 画像/音声解析 | +| `registerImageGenerationProvider` | 画像生成 | +| `registerMusicGenerationProvider` | 音楽生成 | +| `registerVideoGenerationProvider` | 動画生成 | | `registerWebFetchProvider` | Web取得 / スクレイププロバイダー | -| `registerWebSearchProvider` | Web検索 | -| `registerHttpRoute` | HTTPエンドポイント | -| `registerCommand` / `registerCli` | CLIコマンド | -| `registerContextEngine` | コンテキストエンジン | -| `registerService` | バックグラウンドサービス | +| `registerWebSearchProvider` | Web検索 | +| `registerHttpRoute` | HTTPエンドポイント | +| `registerCommand` / `registerCli` | CLIコマンド | +| `registerContextEngine` | コンテキストエンジン | +| `registerService` | バックグラウンドサービス | -型付きライフサイクルフックのフックガード動作: +型付きライフサイクルフックに対するフックガードの動作: -- `before_tool_call`: `{ block: true }` は終端です。より低優先度のハンドラーはスキップされます。 -- `before_tool_call`: `{ block: false }` はno-opであり、以前のblockを解除しません。 -- `before_install`: `{ block: true }` は終端です。より低優先度のハンドラーはスキップされます。 -- `before_install`: `{ block: false }` はno-opであり、以前のblockを解除しません。 -- `message_sending`: `{ cancel: true }` は終端です。より低優先度のハンドラーはスキップされます。 -- `message_sending`: `{ cancel: false }` はno-opであり、以前のcancelを解除しません。 +- `before_tool_call`: `{ block: true }` は終端です。より低い優先度のハンドラーはスキップされます。 +- `before_tool_call`: `{ block: false }` は何もしない動作で、以前の block を解除しません。 +- `before_install`: `{ block: true }` は終端です。より低い優先度のハンドラーはスキップされます。 +- `before_install`: `{ block: false }` は何もしない動作で、以前の block を解除しません。 +- `message_sending`: `{ cancel: true }` は終端です。より低い優先度のハンドラーはスキップされます。 +- `message_sending`: `{ cancel: false }` は何もしない動作で、以前の cancel を解除しません。 型付きフックの完全な動作については、[SDK Overview](/ja-JP/plugins/sdk-overview#hook-decision-semantics) を参照してください。 ## 関連 -- [Building Plugins](/ja-JP/plugins/building-plugins) — 独自Pluginを作成 -- [Plugin Bundles](/ja-JP/plugins/bundles) — Codex/Claude/Cursor Bundle互換 -- [Plugin Manifest](/ja-JP/plugins/manifest) — マニフェストスキーマ -- [Registering Tools](/ja-JP/plugins/building-plugins#registering-agent-tools) — Pluginにエージェントツールを追加 +- [プラグインの構築](/ja-JP/plugins/building-plugins) — 独自のプラグインを作成する +- [プラグインバンドル](/ja-JP/plugins/bundles) — Codex/Claude/Cursorバンドル互換性 +- [プラグインマニフェスト](/ja-JP/plugins/manifest) — マニフェストスキーマ +- [ツールの登録](/ja-JP/plugins/building-plugins#registering-agent-tools) — プラグインにエージェントツールを追加する - [Plugin Internals](/ja-JP/plugins/architecture) — 機能モデルと読み込みパイプライン -- [Community Plugins](/ja-JP/plugins/community) — サードパーティ一覧 +- [コミュニティプラグイン](/ja-JP/plugins/community) — サードパーティの一覧