openclaw secrets

使用 openclaw secrets 管理 SecretRef 並維持執行階段快照的健康狀態。

指令角色：

  • reload：Gateway RPC（secrets.reload），重新解析參照並在全部成功時才替換執行階段快照（不寫入設定）。
  • audit：唯讀掃描設定/驗證/產生的模型儲存區和舊版殘留，檢查明文、未解析的參照及優先順序偏移。
  • configure：互動式規劃器，用於提供者設定、目標對應及預檢（需要 TTY）。
  • apply：執行已儲存的計畫（--dry-run 僅驗證），然後清除目標明文殘留。

建議的操作流程：

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

CI/閘道的結束碼說明：

  • audit --check 發現問題時回傳 1。
  • 未解析的參照回傳 2。

相關資源：

重新載入執行階段快照

重新解析機密參照並原子性地替換執行階段快照。

openclaw secrets reload
openclaw 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 audit
openclaw secrets audit --check
openclaw secrets audit --json

結束行為：

  • --check 發現問題時以非零碼結束。
  • 未解析的參照以較高優先順序的非零碼結束。

報告結構重點：

  • status：clean | findings | unresolved
  • summary：plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount
  • 發現碼：
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

Configure（互動式輔助工具）

以互動方式建構提供者和 SecretRef 變更、執行預檢，並選擇性地套用：

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

流程：

  • 先設定提供者（secrets.providers 別名的新增/編輯/移除）。
  • 再進行憑證對應（選擇欄位並指派 {source, provider, id} 參照）。
  • 最後預檢並選擇性套用。

旗標：

  • --providers-only：僅設定 secrets.providers，跳過憑證對應。
  • --skip-provider-setup：跳過提供者設定，將憑證對應到現有提供者。
  • --agent <id>：將 auth-profiles.json 目標探索和寫入限定在單一代理儲存區。

注意事項：

  • 需要互動式 TTY。
  • 不可同時使用 --providers-only 和 --skip-provider-setup。
  • configure 的目標是 openclaw.json 中含有機密的欄位，以及所選代理範圍的 auth-profiles.json。
  • configure 支援在選擇器流程中直接建立新的 auth-profiles.json 對應。
  • 標準支援範圍：SecretRef Credential Surface。
  • 套用前會執行預檢解析。
  • 產生的計畫預設啟用清除選項（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 以跳過路徑安全性檢查。

套用已儲存的計畫

套用或預檢先前產生的計畫：

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

計畫規範細節（允許的目標路徑、驗證規則和失敗語意）：

apply 可能更新的項目：

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

為什麼沒有回復備份

secrets apply 刻意不寫入包含舊明文值的回復備份。

安全性來自嚴格的預檢 + 近似原子性的套用，以及失敗時盡力而為的記憶體內還原。

範例

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

若 audit --check 仍報告明文發現，請更新其餘報告的目標路徑並重新執行稽核。

arrow_back
上一頁
Sandbox
下一頁
Security
arrow_forward