密鑰套用計畫合約

本頁定義 openclaw secrets 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" },    },  ],}

openclaw secrets configure 會產生此格式的計畫。你也可以手動撰寫或編輯計畫。

提供者的新增或更新與刪除

計畫也可以包含兩個選用的頂層欄位，在寫入各個目標的同時修改 secrets.providers 對應表：

• providerUpserts -- 以提供者別名為鍵的物件。每個值都是提供者定義（格式與 openclaw.json 中 secrets.providers.<alias> 接受的格式相同，例如 exec 或 file 提供者）。
• providerDeletes -- 要移除的提供者別名陣列。

providerUpserts 會在 targets 之前執行，因此 target.ref.provider 可以參照同一計畫在 providerUpserts 中新增的提供者別名。若沒有此執行順序，參照尚未在 openclaw.json 中設定之別名的計畫會失敗，並顯示 provider "<alias>" is not configured。

{  version: 1,  protocolVersion: 1,  providerUpserts: {    onepassword_anthropic: {      source: "exec",      command: "/usr/bin/op",      args: ["read", "op://Vault/Anthropic/credential"],    },  },  providerDeletes: ["legacy_unused_alias"],  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.anthropic.apiKey",      pathSegments: ["models", "providers", "anthropic", "apiKey"],      providerId: "anthropic",      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },    },  ],}

透過 providerUpserts 新增的 Exec 提供者仍須遵守 Exec 提供者同意行為中的 Exec 同意規則：包含 Exec 提供者的計畫在寫入模式下需要使用 --allow-exec。

支援的目標範圍

計畫目標僅接受 SecretRef 憑證介面中支援的憑證路徑。

目標類型行為

target.type 必須是可識別的目標類型，且正規化後的 target.path 必須符合該類型已註冊的路徑格式。

除了標準類型名稱外，部分目標類型也接受相容性別名作為現有計畫的 target.type：

路徑驗證規則

每個目標都會依照以下所有規則進行驗證：

• type 必須是可識別的目標類型。
• path 必須是非空的點號分隔路徑。
• pathSegments 可以省略。若有提供，正規化後必須與 path 完全相同。
• 禁止使用以下區段：__proto__、prototype、constructor。
• 正規化後的路徑必須符合該目標類型已註冊的路徑格式。
• 若設定了 providerId 或 accountId，則必須與路徑中編碼的 ID 相符。
• auth-profiles.json 目標需要 agentId。
• 建立新的 auth-profiles.json 對應時，請包含 authProfileProvider。

失敗行為

若目標驗證失敗，套用作業會結束並顯示類似以下的錯誤：

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

無效計畫不會提交任何寫入：系統會在觸及任何檔案前完成目標解析與路徑驗證。另外，有效計畫開始寫入後，套用作業會先建立所有受影響檔案的快照；若同一次執行中後續的寫入失敗，便會還原這些快照，因此部分寫入絕不會導致設定、驗證設定檔或環境變數狀態不同步。

Exec 提供者同意行為

• --dry-run 預設會略過 Exec SecretRef 檢查。
• 除非設定 --allow-exec，否則在寫入模式下會拒絕包含 Exec SecretRef／提供者的計畫。
• 驗證或套用包含 Exec 的計畫時，請在試執行與寫入命令中都傳入 --allow-exec。

執行階段與稽核範圍說明

• 僅含參照的 auth-profiles.json 項目（keyRef／tokenRef）會納入執行階段憑證解析與稽核涵蓋範圍。
• secrets apply 會寫入支援的 openclaw.json 目標、支援的 auth-profiles.json 目標，以及三個選用且預設啟用的清除程序：scrubEnv（從 .env 移除已遷移的明文值）、scrubAuthProfilesForProviderTargets（針對計畫剛遷移的提供者，清除 auth-profiles.json 中殘留的明文或未使用參照）以及 scrubLegacyAuthJson（從舊版 auth.json 儲存區移除已遷移的 api_key 項目）。若要略過任一程序，請在計畫中將 options.scrubEnv、options.scrubAuthProfilesForProviderTargets 或 options.scrubLegacyAuthJson 設為 false。

操作者檢查

# 驗證計畫但不寫入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-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

若套用作業因無效目標路徑訊息而失敗，請使用 openclaw secrets configure 重新產生計畫，或將目標路徑修正為上述支援的格式。

相關文件

• 密鑰管理
• 命令列介面 secrets
• SecretRef 憑證介面
• 設定參考