Gateway

シークレット適用プランのコントラクト

このページでは、openclaw secrets apply によって適用される厳密な契約を定義します。ターゲットがこれらのルールに一致しない場合、apply はファイルを変更する前に失敗します。

プランファイルの形式

openclaw secrets apply --from <plan.json> は、プランターゲットの targets 配列を想定します。

json5

{  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" },    },  ],}

openclaw secrets configure はこの形式のプランを生成します。手動で作成または編集することもできます。

プロバイダーの追加・更新と削除

プランには、ターゲットごとの書き込みとともに 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 というエラーで失敗します。

json5

{  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 が必要です。

サポート対象のターゲット範囲

プランターゲットは、SecretRef 認証情報サーフェスに記載されたサポート対象の認証情報パスで受け付けられます。

ターゲット型の動作

target.type は認識可能なターゲット型である必要があり、正規化された target.path はその型に登録されたパス形式と一致する必要があります。

一部のターゲット型では、既存のプラン向けに、正規の型名に加えて互換性エイリアスを target.type として受け付けます。

正規の型	受け付けるエイリアス
`models.providers.apiKey`	`models.providers.*.apiKey`
`skills.entries.apiKey`	`skills.entries.*.apiKey`
`channels.googlechat.serviceAccount`	`channels.googlechat.accounts.*.serviceAccount`

パス検証ルール

各ターゲットは、次のすべての条件で検証されます。

type は認識可能なターゲット型である必要があります。
path は空でないドット区切りパスである必要があります。
pathSegments は省略できます。指定する場合、正規化後のパスが path と完全に一致する必要があります。
禁止されているセグメント __proto__、prototype、constructor は拒否されます。
正規化されたパスは、ターゲット型に登録されたパス形式と一致する必要があります。
providerId または accountId が設定されている場合、パスにエンコードされた ID と一致する必要があります。
auth-profiles.json のターゲットには agentId が必要です。
新しい auth-profiles.json マッピングを作成する場合は、authProfileProvider を含めます。

失敗時の動作

ターゲットが検証に失敗した場合、apply は次のようなエラーを出して終了します。

text

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

無効なプランでは、書き込みは一切確定されません。ターゲットの解決とパスの検証は、ファイルに触れる前に実行されます。また、有効なプランが書き込みを開始すると、apply は最初に変更対象のすべてのファイルのスナップショットを作成し、同じ実行内の後続の書き込みが失敗した場合はそれらのスナップショットを復元します。そのため、部分的な書き込みによって設定、認証プロファイル、または環境変数の状態が不整合になることはありません。

Exec プロバイダーの同意動作

--dry-run は、デフォルトで exec SecretRef のチェックを省略します。
exec SecretRef またはプロバイダーを含むプランは、--allow-exec が設定されていない限り、書き込みモードで拒否されます。
exec を含むプランを検証または適用する場合は、ドライランと書き込みの両方のコマンドに --allow-exec を渡します。

ランタイムと監査範囲に関する注意事項

参照のみの auth-profiles.json エントリ（keyRef/tokenRef）は、ランタイムの認証情報解決と監査の対象に含まれます。
secrets apply は、サポート対象の openclaw.json ターゲットと auth-profiles.json ターゲットに書き込み、さらにデフォルトで有効な3つの省略可能なスクラブ処理を実行します。scrubEnv（移行済みの平文値を .env から削除）、scrubAuthProfilesForProviderTargets（プランで移行したプロバイダーについて、auth-profiles.json に残る平文または未使用の参照を消去）、scrubLegacyAuthJson（従来の auth.json ストアから移行済みの api_key エントリを削除）です。処理を省略するには、プラン内の options.scrubEnv、options.scrubAuthProfilesForProviderTargets、options.scrubLegacyAuthJson のいずれかを false に設定します。

運用者向け確認手順

bash

# 書き込まずにプランを検証openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # 続いて実際に適用openclaw secrets apply --from /tmp/openclaw-secrets-plan.json # exec を含むプランでは、両方のモードで明示的に許可openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

無効なターゲットパスを示すメッセージで apply が失敗した場合は、openclaw secrets configure でプランを再生成するか、ターゲットパスを上記のサポート対象形式に修正してください。