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。
相關：
- Secrets 指南：Secrets Management
- Credential surface：SecretRef Credential Surface
- 安全性指南：Security
重新載入執行時段快照
Section titled “重新載入執行時段快照”重新解析機密參照並以原子方式交換執行時段快照。
openclaw secrets reloadopenclaw secrets reload --jsonopenclaw secrets reload --url ws://127.0.0.1:18789 --token <token>說明：
- 使用 gateway RPC 方法
secrets.reload。 - 如果解析失敗，gateway 會保持最後一個已知的良好快照並傳回錯誤（無部分啟用）。
- JSON 回應包含
warningCount。
選項：
--url <url>--token <token>--timeout <ms>--json
掃描 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目標探索與寫入範圍限制在單一 agent store。--allow-exec：允許在 preflight/apply 期間執行 SecretRef 檢查（可能會執行提供者指令）。
備註：
- 需要互動式 TTY。
- 您不能將
--providers-only與--skip-provider-setup結合使用。 configure的目標是openclaw.json中包含秘密的欄位，加上所選 agent 範圍的auth-profiles.json。configure支援直接在選擇器流程中建立新的auth-profiles.json映射。- 標準的支援介面：SecretRef Credential Surface。
- 它會在 apply 之前執行 preflight 解析。
- 如果 preflight/apply 包含 exec refs，請將
--allow-exec在兩個步驟中都保持設定。 - 產生的計畫預設使用清理選項（
scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson均已啟用）。 - 針對已清理的明文值，Apply 路徑是單向的。
- 如果沒有
--apply，CLI 仍會在 preflight 後提示Apply this plan now?。 - 使用
--apply（且沒有--yes）時，CLI 會提示額外的不可逆確認。 --json會列印計畫 + preflight 報告，但該指令仍需要互動式 TTY。
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會驗證預檢而不寫入檔案。- 在 dry-run 模式下，exec SecretRef 檢查預設會被跳過。
- 除非設定了
--allow-exec，否則寫入模式會拒絕包含 exec SecretRefs/提供者的計畫。 - 使用
--allow-exec可在任一模式下選擇加入 exec 提供者檢查/執行。
計畫合約細節（允許的目標路徑、驗證規則和失敗語意）：
apply 可能會更新的內容：
openclaw.json(SecretRef 目標 + 提供者 upserts/刪除)auth-profiles.json(提供者目標清除)- 舊版
auth.json殘留 ~/.openclaw/.env已遷移值的已知金鑰
為何沒有還原備份
Section titled “為何沒有還原備份”secrets apply 故意不寫入包含舊明文值的還原備份。
安全性來自於嚴格的預檢 + 原子式套用，並在失敗時盡力進行記憶體內還原。
openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check如果 audit --check 仍然回報明文發現，請更新剩餘回報的目標路徑並重新執行稽核。