Gateway
シークレット適用計画のコントラクト
このページは、openclaw secrets apply によって強制される厳密な契約を定義します。
ターゲットがこれらのルールに一致しない場合、apply は設定を変更する前に失敗します。
プランファイルの形式
openclaw secrets apply --from <plan.json> は、プランターゲットの targets 配列を期待します。
{ version: 1, protocolVersion: 1, targets: [ { type: "models.providers.apiKey", path: "models.providers.openai.apiKey", pathSegments: ["models", "providers", "openai", "apiKey"], providerId: "openai", ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" }, }, { type: "auth-profiles.api_key.key", path: "profiles.openai:default.key", pathSegments: ["profiles", "openai:default", "key"], agentId: "main", ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" }, }, ],}プロバイダーの upsert と削除
プランには、ターゲットごとの書き込みと並行して secrets.providers マップを変更する、任意のトップレベルフィールドを 2 つ含めることもできます。
providerUpserts— プロバイダー別名をキーにしたオブジェクトです。各値はプロバイダー定義です（openclaw.jsonのsecrets.providers.<alias>で受け付けられるものと同じ形式。たとえばexecまたはfileプロバイダー）。providerDeletes— 削除するプロバイダー別名の配列です。
providerUpserts は targets より前に実行されるため、target.ref.provider は同じプランが providerUpserts で導入するプロバイダー別名を参照できます。これがない場合、openclaw.json にまだ設定されていない別名を参照するプランは provider "<alias>" is not configured で失敗します。
{ version: 1, protocolVersion: 1, providerUpserts: { onepassword_anthropic: { source: "exec", command: "/usr/bin/op", args: ["read", "op://Vault/Anthropic/credential"], }, }, providerDeletes: ["legacy_unused_alias"], targets: [ { type: "models.providers.apiKey", path: "models.providers.anthropic.apiKey", pathSegments: ["models", "providers", "anthropic", "apiKey"], providerId: "anthropic", ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" }, }, ],}providerUpserts で導入された exec プロバイダーにも、Exec プロバイダーの同意動作 の exec 同意ルールが適用されます。exec プロバイダーを含むプランでは、書き込みモードで --allow-exec が必要です。
サポートされるターゲット範囲
プランターゲットは、次のサポート対象の認証情報パスで受け付けられます。
ターゲットタイプの動作
一般ルール:
target.typeは認識される必要があり、正規化されたtarget.pathの形式と一致している必要があります。
既存のプラン向けに、互換性別名は引き続き受け付けられます。
models.providers.apiKeyskills.entries.apiKeychannels.googlechat.serviceAccount
パス検証ルール
各ターゲットは、次のすべてで検証されます。
typeは認識されるターゲットタイプである必要があります。pathは空でないドットパスである必要があります。pathSegmentsは省略できます。指定する場合、pathとまったく同じパスに正規化される必要があります。- 禁止されたセグメントは拒否されます:
__proto__、prototype、constructor。 - 正規化されたパスは、ターゲットタイプに登録されたパス形式と一致する必要があります。
providerIdまたはaccountIdが設定されている場合、パスにエンコードされた ID と一致する必要があります。auth-profiles.jsonターゲットにはagentIdが必要です。- 新しい
auth-profiles.jsonマッピングを作成する場合は、authProfileProviderを含めます。
失敗時の動作
ターゲットが検証に失敗した場合、apply は次のようなエラーで終了します。
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl無効なプランでは書き込みはコミットされません。
Exec プロバイダーの同意動作
--dry-runは、デフォルトで exec SecretRef チェックをスキップします。- exec SecretRef/プロバイダーを含むプランは、
--allow-execが設定されていない限り、書き込みモードで拒否されます。 - exec を含むプランを検証または適用する場合は、dry-run と書き込みコマンドの両方で
--allow-execを渡します。
ランタイムと監査範囲の注記
- ref のみの
auth-profiles.jsonエントリ（keyRef/tokenRef）は、ランタイム解決と監査対象に含まれます。 secrets applyは、サポート対象のopenclaw.jsonターゲット、サポート対象のauth-profiles.jsonターゲット、および任意のスクラブターゲットを書き込みます。
オペレーターチェック
# Validate plan without writesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # Then apply for realopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json # For exec-containing plans, opt in explicitly in both modesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execapply が無効なターゲットパスのメッセージで失敗した場合は、openclaw secrets configure でプランを再生成するか、ターゲットパスを上記のサポート対象形式に修正してください。
