OpenClaw Secrets Apply：掌握 Plan 檔案結構與驗證規範

在管理不同環境的 Secret 時，最怕的就是手滑填錯路徑，導致整個服務掛掉。為了幫你把關，openclaw 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 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

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

```bash
# 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