OpenClaw secrets apply：プラン契約とバリデーション仕様を解説

開発を進める中で、API キーや認証情報の管理は常に神経を使う作業ですよね。設定ファイルのパスを一つ間違えただけで、デプロイ後にエラーが発生して慌てて修正する、といった経験は誰にでもあるはずです。

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 Credential Surface

ターゲットタイプの動作

基本的なルールは以下の通りです。

target.type が認識可能であり、正規化された target.path の形式と一致している必要があります。

既存のプランについては、以下の互換性エイリアスも引き続き使用可能です。

models.providers.apiKey
skills.entries.apiKey
channels.googlechat.serviceAccount

パス検証ルール

各ターゲットは、以下のすべての項目で検証されます。

type は認識されたターゲットタイプであること。
path は空でないドット形式のパス（dot 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

無効なプランに対して、書き込み（コミット）が行われることはありません。

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

keyRef や tokenRef を使用した参照のみの auth-profiles.json エントリは、ランタイムの解決および監査の対象に含まれます。
secrets apply は、サポートされている openclaw.json ターゲット、 auth-profiles.json ターゲット、およびオプションの scrub ターゲットを書き込みます。

オペレーターによる確認

実際に設定を反映する前に、以下のコマンドで検証を行うのがベストプラクティスです。

# Validate plan without writes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Then apply for real
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

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

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。