Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw secrets
使用 openclaw secrets 管理 SecretRef，並保持作用中的執行階段快照健康。
命令角色：
reload：Gateway RPC（secrets.reload），會重新解析 ref，且僅在完全成功時替換執行階段快照（不寫入設定）。audit：唯讀掃描設定、驗證、產生的模型儲存區和舊版殘留，檢查明文、未解析的 ref，以及優先順序漂移（除非設定--allow-exec，否則會略過 exec ref）。configure：用於提供者設定、目標對應和預檢的互動式規劃器（需要 TTY）。apply：執行已儲存的計畫（--dry-run僅用於驗證；dry-run 預設會略過 exec 檢查，而寫入模式會拒絕包含 exec 的計畫，除非設定--allow-exec），然後清除目標明文殘留。
exec SecretRef/提供者，請在 dry-run 和寫入 apply 命令中都傳入 --allow-exec。
CI/閘門的結束代碼注意事項：
audit --check發現問題時會傳回1。- 未解析的 ref 會傳回
2。
- 秘密指南：Secrets Management
- 憑證介面：SecretRef Credential Surface
- 安全性指南：Security
重新載入執行階段快照
重新解析秘密 ref，並以原子方式替換執行階段快照。- 使用 Gateway RPC 方法
secrets.reload。 - 如果解析失敗，Gateway 會保留最後已知正常的快照並傳回錯誤（不會部分啟用）。
- JSON 回應包含
warningCount。
--url <url>--token <token>--timeout <ms>--json
稽核
掃描 OpenClaw 狀態以檢查：- 明文秘密儲存
- 未解析的 ref
- 優先順序漂移（
auth-profiles.json憑證遮蔽openclaw.jsonref） - 產生的
agents/*/agent/models.json殘留（提供者apiKey值和敏感提供者標頭） - 舊版殘留（舊版驗證儲存項目、OAuth 提醒）
- 敏感提供者標頭偵測是以名稱啟發式為基礎（常見驗證/憑證標頭名稱，以及像
authorization、x-api-key、token、secret、password和credential這類片段）。
--check發現問題時會以非零代碼結束。- 未解析的 ref 會以較高優先級的非零代碼結束。
status：clean | findings | unresolvedresolution：refsChecked、skippedExecRefs、resolvabilityCompletesummary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount- 發現代碼：
PLAINTEXT_FOUNDREF_UNRESOLVEDREF_SHADOWEDLEGACY_RESIDUE
設定（互動式輔助工具）
以互動方式建置提供者和 SecretRef 變更、執行預檢，並可選擇套用：- 先設定提供者（對
secrets.providers別名進行add/edit/remove）。 - 再對應憑證（選取欄位並指派
{source, provider, id}ref）。 - 最後執行預檢並可選擇套用。
--providers-only：只設定secrets.providers，略過憑證對應。--skip-provider-setup：略過提供者設定，並將憑證對應到現有提供者。--agent <id>：將auth-profiles.json目標探索和寫入限定到一個代理程式儲存區。--allow-exec：允許在預檢/apply 期間執行 exec SecretRef 檢查（可能會執行提供者命令）。
- 需要互動式 TTY。
- 你不能將
--providers-only與--skip-provider-setup組合使用。 configure會以openclaw.json中帶有秘密的欄位為目標，並包含所選代理程式範圍的auth-profiles.json。configure支援直接在選取器流程中建立新的auth-profiles.json對應。- 標準支援介面：SecretRef Credential Surface。
- 它會在套用前執行預檢解析。
- 如果預檢/apply 包含 exec ref，請在兩個步驟都保持設定
--allow-exec。 - 產生的計畫預設啟用清除選項（
scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson全部啟用）。 - apply 路徑對已清除的明文值是單向的。
- 若未使用
--apply，CLI 仍會在預檢後提示Apply this plan now?。 - 使用
--apply（且沒有--yes）時，CLI 會提示額外的不可逆確認。 --json會列印計畫和預檢報告，但命令仍需要互動式 TTY。
- Homebrew 安裝通常會在
/opt/homebrew/bin/*下公開符號連結的二進位檔。 - 僅在受信任套件管理器路徑需要時，才設定
allowSymlinkCommand: true，並搭配trustedDirs（例如["/opt/homebrew"]）。 - 在 Windows 上，如果無法對提供者路徑進行 ACL 驗證，OpenClaw 會採取失敗關閉。僅對受信任路徑，在該提供者上設定
allowInsecurePath: true以略過路徑安全性檢查。
套用已儲存的計畫
套用或預檢先前產生的計畫：--dry-run會驗證預檢而不寫入檔案。- dry-run 預設會略過 exec SecretRef 檢查。
- 寫入模式會拒絕包含 exec SecretRef/提供者的計畫，除非設定
--allow-exec。 - 使用
--allow-exec在任一模式中選擇加入 exec 提供者檢查/執行。
apply 可能更新的內容：
openclaw.json（SecretRef 目標 + 提供者 upsert/delete）auth-profiles.json（提供者目標清除）- 舊版
auth.json殘留 ~/.openclaw/.env中已遷移其值的已知秘密鍵
為什麼沒有復原備份
secrets apply 刻意不寫入包含舊明文值的復原備份。
安全性來自嚴格預檢，以及失敗時盡力進行記憶體內還原的近似原子套用。
範例
audit --check 仍回報明文發現項目，請更新剩餘回報的目標路徑並重新執行稽核。