secrets
openclaw secrets
Section titled “openclaw secrets”使用 openclaw secrets 來管理 SecretRefs 並保持作用中的執行時段快照健全。
指令角色：
reload：gateway RPC (secrets.reload)，會重新解析參照並僅在完全成功時交換執行時段快照（無組態寫入）。audit：對組態/認證/生成模型儲存及舊殘留進行唯讀掃描，以查找明文、未解析的參照及優先順序漂移（除非設定了--allow-exec，否則會跳過 exec 參照）。configure：用於提供者設定、目標映射及預檢的互動式規劃程式（需要 TTY）。apply：執行已儲存的計畫（--dry-run僅用於驗證；試執行預設會跳過 exec 檢查，而寫入模式會拒絕包含 exec 的計畫，除非設定了--allow-exec），然後清除目標明文殘留。
建議的操作員循環：
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets audit --checkopenclaw secrets reload如果您的計畫包含 exec SecretRefs/提供者，請在試執行和寫入套用指令上傳遞 --allow-exec。
CI/閘道的結束代碼說明：
audit --check在發現結果時會傳回1。- 未解析的參照會傳回
2。
相關：
- 機密指南：機密管理
- 憑證接觸面：SecretRef 憑證接觸面
- 安全性指南：安全性
重新載入執行時段快照
Section titled “重新載入執行時段快照”重新解析機密參照並以原子方式交換執行時段快照。
openclaw secrets reloadopenclaw secrets reload --json說明：
- 使用 gateway RPC 方法
secrets.reload。 - 如果解析失敗，gateway 會保持最後一個已知的良好快照並傳回錯誤（無部分啟用）。
- JSON 回應包含
warningCount。
掃描 OpenClaw 狀態以尋找：
- 明文機密儲存
- 未解析的參照
- 優先級漂移（
auth-profiles.json憑證遮蔽openclaw.json參照） - 產生的
agents/*/agent/models.json殘留（提供者apiKey值和敏感的提供者標頭） - 舊版殘留（舊版認證儲存條目、OAuth 提醒）
標頭殘留說明：
- 敏感提供者標頭偵測是基於名稱啟發式（常見的認證/憑證標頭名稱和片段，例如
authorization、x-api-key、token、secret、password和credential）。
openclaw secrets auditopenclaw secrets audit --checkopenclaw secrets audit --jsonopenclaw secrets audit --allow-exec結束行為：
- 當發現問題時，
--check會以非零狀態碼結束。 - 未解析的參照會以更高優先級的非零狀態碼結束。
報告結構重點：
status：clean | findings | unresolvedresolution：refsChecked、skippedExecRefs、resolvabilityCompletesummary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount- 發現代碼：
PLAINTEXT_FOUNDREF_UNRESOLVEDREF_SHADOWEDLEGACY_RESIDUE
設定（互動式助手）
Section titled “設定（互動式助手）”以互動方式建構提供者和 SecretRef 變更，執行預檢，並選擇性套用：
openclaw secrets configureopenclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.jsonopenclaw secrets configure --apply --yesopenclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent opsopenclaw secrets configure --json流程：
- 首先設定提供者（使用
add/edit/remove進行secrets.providers別名設定）。 - 接著進行憑證對應（選擇欄位並指派
{source, provider, id}參照）。 - 最後進行預檢和選擇性套用。
旗標：
--providers-only：僅設定secrets.providers，跳過憑證對應。--skip-provider-setup：跳過提供者設定，並將憑證對應至現有提供者。--agent <id>：將auth-profiles.json目標探索和寫入範圍限制在一個代理程式儲存中。--allow-exec：允許在預檢/套用期間執行 exec SecretRef 檢查（可能會執行提供者指令）。
說明：
- 需要互動式 TTY。
- 您不能將
--providers-only與--skip-provider-setup結合使用。 configure以openclaw.json中的承載密碼欄位為目標，加上所選代理程式範圍的auth-profiles.json。configure支援直接在選擇器流程中建立新的auth-profiles.json對應。- 標準的支援介面：SecretRef Credential Surface。
- 它會在套用前執行預檢解析。
- 如果預檢/套用包含 exec refs，請在這兩個步驟中保持
--allow-exec設定。 - 產生的計畫預設為清除選項 (
scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson全部啟用)。 - 清除後的明文值的套用路徑是單向的。
- 若沒有
--apply，CLI 仍會在預檢後提示Apply this plan now?。 - 使用
--apply(且沒有--yes) 時，CLI 會提示額外的不可逆確認。
Exec 提供者安全注意事項：
- Homebrew 安裝通常會在
/opt/homebrew/bin/*下公開符號連結二元檔。 - 僅在信任的套件管理器路徑需要時設定
allowSymlinkCommand: true，並將其與trustedDirs搭配使用 (例如["/opt/homebrew"])。 - 在 Windows 上，如果無法針對提供者路徑使用 ACL 驗證，OpenClaw 將會封閉式失敗。僅針對信任的路徑，請在該提供者上設定
allowInsecurePath: true以略過路徑安全檢查。
套用已儲存的計畫
Section titled “套用已儲存的計畫”套用或預檢先前產生的計畫：
openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --jsonExec 行為：
--dry-run會驗證預檢而不寫入檔案。- 在試執行中，exec SecretRef 檢查預設會被略過。
- 寫入模式會拒絕包含 exec SecretRefs/提供者的計畫，除非已設定
--allow-exec。 - 使用
--allow-exec以選擇在任一模式中執行 exec 提供者檢查/執行。
計畫契約詳細資訊 (允許的目標路徑、驗證規則和失敗語意)：
apply 可能更新的內容：
openclaw.json(SecretRef 目標 + 提供者新增/刪除)auth-profiles.json(提供者目標清理)- 舊版
auth.json殘留 ~/.openclaw/.env值已遷移的已知金鑰
為何沒有回滾備份
Section titled “為何沒有回滾備份”secrets apply 刻意不寫入包含舊純文字值的回滾備份。
安全性來自嚴格的飛行前檢查 + 類原子的套用，並在失敗時盡力在記憶體中還原。
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check如果 audit --check 仍然回報純文字結果，請更新其餘回報的目標路徑並重新執行稽核。