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。如果解析失敗，閘道會保留其最後已知良好的快照並傳回錯誤（不會部分啟用）。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

報告結構：

• 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）。套用後，已清除的明文值無法復原。
• 未使用 --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 提供者檢查／執行。

apply 可能更新：

• openclaw.json（SecretRef 目標與提供者新增或更新／刪除）
• auth-profiles.json（提供者目標清除）
• 舊版 auth.json 殘留
• ~/.openclaw/.env 中其值已移轉的已知密鑰鍵

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

為何沒有復原備份

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

範例

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

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

相關內容

• 命令列介面參考
• 密鑰管理
• Vault SecretRef