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 重新產生計畫，或修正目標路徑為上述支援的格式。