openclaw secrets apply によって適用される厳密な契約を定義します。ターゲットがこれらのルールに一致しない場合、ファイルを変更する前に適用が失敗します。
プランファイルの要件
openclaw secrets apply --from <plan.json> は、最大 16 MiB（16,777,216 バイト）の通常ファイルを受け付けます。この制限は、空白を含むシリアライズ済みファイル全体に適用されます。ディレクトリ、FIFO、デバイスファイル、および制限を超えるファイルは、JSON の解析またはターゲットの検証前に拒否されます。
openclaw secrets configure --plan-out <plan.json> は、ファイルを作成する前に、UTF-8 でシリアライズされた出力にも同じ制限を適用します。手書きのプランと外部プランジェネレーターでも、シリアライズ済みファイルをこの制限内に収める必要があります。
プランファイルの形式
openclaw secrets apply --from <plan.json> は、プランターゲットの targets 配列を想定します。
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 で失敗します。
providerUpserts を介して導入された exec プロバイダーにも、exec プロバイダーの同意動作に記載された exec 同意ルールが適用されます。exec プロバイダーを含むプランでは、書き込みモードで --allow-exec が必要です。
サポートされるターゲット範囲
SecretRef 認証情報サーフェスに記載された、サポート対象の認証情報パスのプランターゲットが受け付けられます。ターゲットタイプの動作
target.type は認識されるターゲットタイプでなければならず、正規化された target.path は、そのタイプに登録されたパス形式と一致する必要があります。
一部のターゲットタイプでは、正規のタイプ名に加え、既存のプラン向けに target.type として互換性エイリアスを受け付けます。
パス検証ルール
各ターゲットは、次のすべての条件に基づいて検証されます。typeは、認識されるターゲットタイプである必要があります。pathは、空でないドット区切りのパスである必要があります。pathSegmentsは省略できます。指定する場合は、正規化後にpathと完全に同じパスになる必要があります。- 禁止されているセグメントは拒否されます：
__proto__、prototype、constructor。 - 正規化されたパスは、ターゲットタイプに登録されたパス形式と一致する必要があります。
providerIdまたはaccountIdが設定されている場合、パスにエンコードされた ID と一致する必要があります。auth-profiles.jsonターゲットにはagentIdが必要です。- 新しい
auth-profiles.jsonマッピングを作成する場合は、authProfileProviderを含めます。
失敗時の動作
ターゲットの検証に失敗すると、適用処理は次のようなエラーで終了します。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に設定します。
オペレーターによる確認
openclaw secrets configure でプランを再生成するか、ターゲットパスを上記のサポート対象形式に修正します。