Secrets Apply プランコントラクト

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

サポート対象のターゲットスコープ

プランターゲットは以下のサポート対象クレデンシャルパスで受け付けられます：

SecretRef クレデンシャルサーフェス

ターゲットタイプの動作

基本ルール：

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

無効なプランでは書き込みは一切コミットされません。

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

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

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