Gateway
Secrets適用プランコントラクト
このページでは、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.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を含むプランを検証/適用する場合は、ドライランと書き込みコマンドの両方で
--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でプランを再生成するか、上記のサポートされる形式にターゲットパスを修正してください。