メインコンテンツへスキップ

​
Secrets apply plan contract

このページでは、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" },
    },
  ],
}

​
サポートされるターゲットスコープ

プランターゲットは、次に含まれるサポート対象の認証情報パスに対して受け付けられます:

​
ターゲット種別の動作

一般ルール:
  • target.typeは認識される必要があり、正規化されたtarget.pathの形状と一致している必要があります。
既存プランとの互換性エイリアスは引き続き受け付けられます:
  • models.providers.apiKey
  • skills.entries.apiKey
  • channels.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 SecretRefs/providersを含むプランは、--allow-execが設定されていない限り、書き込みモードでは拒否されます。
  • execを含むプランを検証/適用する場合は、dry-runと書き込みコマンドの両方で--allow-execを渡してください。

​
ランタイムおよび監査スコープに関する注記

  • refのみのauth-profiles.jsonエントリ（keyRef/tokenRef）は、ランタイム解決と監査対象に含まれます。
  • secrets applyは、サポートされるopenclaw.jsonターゲット、サポートされるauth-profiles.jsonターゲット、および任意のスクラブターゲットを書き込みます。

​
オペレーターチェック

# 書き込みなしでプランを検証
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-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
無効なターゲットパスメッセージでapplyが失敗した場合は、openclaw secrets configureでプランを再生成するか、上記のサポートされる形状にターゲットパスを修正してください。

​
関連ドキュメント