openclaw secrets

管理 SecretRef，並維持作用中執行階段快照的健康狀態。

建議的操作員流程：

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 SecretRef／提供者，請在試執行與寫入的 apply 命令中都傳入 --allow-exec。

CI／閘門的結束代碼：

• audit --check 發現問題時會傳回 1。
• 未解析的參照會傳回 2（無論是否使用 --check）。

相關內容：機密資料管理 · SecretRef 認證資訊介面 · 安全性

重新載入執行階段快照

openclaw secrets reloadopenclaw secrets reload --jsonopenclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

使用閘道 RPC 方法 secrets.reload。健康的擁有者會各自重新整理。只有在參照識別資訊、提供者定義及完整的非機密擁有者合約均未變更時，符合條件但失敗的擁有者才會變為過期狀態；新增或已變更的失敗會變為冷啟動狀態。這種降級啟用會成功，並回報 warningCount。嚴格模式或未對應的失敗會傳回錯誤，並保留先前作用中的快照。

選項：--url <url>、--token <token>、--timeout <ms>、--json。

稽核

掃描 OpenClaw 狀態，檢查：

• 以明文儲存機密資料
• 未解析的參照
• 優先順序偏移（auth-profiles.json 認證資訊遮蔽 openclaw.json 參照）
• 產生的 agents/*/agent/models.json 殘留項目（提供者 apiKey 值與敏感的提供者標頭）
• 舊版殘留項目（舊版驗證儲存區項目、OAuth 提醒）

.env 掃描涵蓋有效的狀態目錄，以及包含作用中設定的目錄。當兩個路徑指向同一個檔案時，只會掃描一次。

敏感提供者標頭的偵測以名稱啟發法為基礎：名稱符合常見驗證／認證資訊片段（authorization、x-api-key、token、secret、password、credential）的標頭會被標記。

openclaw secrets auditopenclaw secrets audit --checkopenclaw secrets audit --jsonopenclaw secrets audit --allow-exec

報告格式：

• status：clean | findings | unresolved
• resolution：refsChecked、skippedExecRefs、resolvabilityComplete
• summary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount
• 發現項目代碼：PLAINTEXT_FOUND、REF_UNRESOLVED、REF_SHADOWED、LEGACY_RESIDUE

設定（互動式輔助工具）

以互動方式建立提供者與 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

流程：先設定提供者（新增／編輯／移除 secrets.providers 別名），再對應認證資訊（選取欄位、指派 {source, provider, id} 參照），接著執行預檢，並選擇性套用。

旗標：

• --providers-only：僅設定 secrets.providers，略過認證資訊對應
• --skip-provider-setup：略過提供者設定，將認證資訊對應至現有提供者
• --agent <id>：將 auth-profiles.json 目標探索與寫入範圍限定為單一代理程式儲存區
• --allow-exec：允許在預檢／套用期間執行 exec SecretRef 檢查（可能會執行提供者命令）

--providers-only 與 --skip-provider-setup 無法併用。

注意事項：

• 需要互動式 TTY。
• 以 openclaw.json 中含有機密資料的欄位，以及所選代理程式範圍的 auth-profiles.json 為目標；標準支援介面：SecretRef 認證資訊介面。
• 支援直接在選取器流程中建立新的 auth-profiles.json 對應。
• 在套用前執行預檢解析。
• 產生的計畫預設會啟用清除選項（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson）。已清除的明文值無法透過套用還原。
• --plan-out 會拒絕建立 UTF-8 序列化形式超過 16 MiB（16,777,216 bytes）的計畫，與 apply --from 的輸入限制一致。
• 若未使用 --apply，命令列介面仍會在預檢後提示 Apply this plan now?。
• 使用 --apply（且未使用 --yes）時，命令列介面會額外提示不可逆移轉確認。
• --json 會印出計畫與預檢報告，但仍需要互動式 TTY。

Exec 提供者安全性

Homebrew 安裝通常會在 /opt/homebrew/bin/* 下公開符號連結的二進位檔。只有受信任的套件管理器路徑需要時，才設定 allowSymlinkCommand: true，並搭配 trustedDirs（例如 ["/opt/homebrew"]）。在 Windows 上，如果無法驗證提供者路徑的 ACL，OpenClaw 會採取失敗關閉；僅針對受信任的路徑，可在該提供者上設定 allowInsecurePath: true，以略過路徑安全性檢查。

套用已儲存的計畫

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 --json

--dry-run 會驗證預檢而不寫入檔案；試執行預設會略過 exec SecretRef 檢查。除非使用 --allow-exec，否則寫入模式會拒絕包含 exec SecretRef／提供者的計畫。使用 --allow-exec 可在任一模式中選擇啟用 exec 提供者檢查／執行。

--from 必須指向不超過 16 MiB（16,777,216 bytes）的普通檔案。位元組限制適用於完整的序列化檔案，包括空白字元。

apply 可能更新的項目：

• openclaw.json（SecretRef 目標與提供者更新插入／刪除）
• auth-profiles.json（清除提供者目標）
• 舊版 auth.json 殘留項目
• 有效狀態與作用中設定目錄中的 .env 檔案，針對值已移轉的已知機密金鑰

計畫合約詳細資料（允許的目標路徑、驗證規則、失敗語意）：機密資料套用計畫合約。

為何沒有復原備份

secrets apply 刻意不寫入包含舊明文值的復原備份。安全性來自嚴格的預檢與近似不可分割的套用，並在失敗時盡力於記憶體中還原。

範例

openclaw secrets audit --checkopenclaw secrets configureopenclaw secrets audit --check

如果 audit --check 仍回報明文發現項目，請更新其餘回報的目標路徑，然後重新執行稽核。

相關內容

• 命令列介面參考
• 機密資料管理
• Vault SecretRef