機密管理

• 已停用的頻道/帳號項目。
• 沒有任何已啟用帳號繼承的頂層頻道憑證。
• 已停用的工具/功能表面。
• 未被 tools.web.search.provider 選取的網路搜尋提供者專用金鑰。在自動模式（未設定提供者）中，金鑰會依優先順序供提供者自動偵測使用，直到有一個解析成功。選取後，未選取的提供者金鑰會被視為非作用中，直到被選取為止。
• Sandbox SSH 驗證資料（agents.defaults.sandbox.ssh.identityData、certificateData、knownHostsData，加上個別 agent 覆寫）只有在預設 agent 或已啟用 agent 的有效 sandbox 後端為 ssh 時才是作用中。
• gateway.remote.token / gateway.remote.password SecretRefs 在以下任一條件成立時為作用中：
  • gateway.mode=remote
  • 已設定 gateway.remote.url
  • gateway.tailscale.mode 為 serve 或 funnel
  • 在沒有這些遠端表面的本機模式中：
    • 當權杖驗證可勝出且未設定 env/auth 權杖時，gateway.remote.token 為作用中。
    • 只有在密碼驗證可勝出且未設定 env/auth 密碼時，gateway.remote.password 才為作用中。
• 當設定 OPENCLAW_GATEWAY_TOKEN 時，gateway.auth.token SecretRef 在啟動驗證解析中為非作用中，因為 env 權杖輸入會在該執行階段勝出。

• 可選擇透過 allowlist 設定允許清單。
• 缺少/空白 env 值會讓解析失敗。

• 從 path 讀取本機檔案。
• mode: "json" 預期 JSON 物件 payload，並將 id 解析為 pointer。
• mode: "singleValue" 預期 ref id "value"，並回傳檔案內容。
• 路徑必須通過擁有權/權限檢查。
• Windows fail-closed 注意事項：如果某個路徑無法進行 ACL 驗證，解析會失敗。僅對受信任路徑，可在該提供者上設定 allowInsecurePath: true 以略過路徑安全檢查。

• 執行已設定的絕對二進位檔路徑，不使用 shell。
• 預設情況下，command 必須指向一般檔案（不是 symlink）。
• 設定 allowSymlinkCommand: true 以允許 symlink 命令路徑（例如 Homebrew shims）。OpenClaw 會驗證解析後的目標路徑。
• 將 allowSymlinkCommand 與 trustedDirs 搭配用於套件管理器路徑（例如 ["/opt/homebrew"]）。
• 支援 timeout、no-output timeout、輸出位元組限制、env 允許清單，以及受信任目錄。
• Windows fail-closed 注意事項：如果命令路徑無法進行 ACL 驗證，解析會失敗。僅對受信任路徑，可在該提供者上設定 allowInsecurePath: true 以略過路徑安全檢查。

請求 payload（stdin）：

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

回應 payload（stdout）：

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

可選的逐 id 錯誤：

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

發現項目包括：

• 靜態儲存的明文值（openclaw.json、auth-profiles.json、.env，以及產生的 agents/*/agent/models.json）
• 產生的 models.json 項目中，明文敏感 provider header 殘留
• 未解析的 refs
• 優先順序遮蔽（auth-profiles.json 優先於 openclaw.json refs）
• 舊版殘留（auth.json、OAuth 提醒）

Exec 注意事項：

• 預設情況下，稽核會略過 exec SecretRef 可解析性檢查，以避免命令副作用。
• 使用 openclaw secrets audit --allow-exec 可在稽核期間執行 exec providers。

Header 殘留注意事項：

• 敏感 provider header 偵測是以名稱啟發式為基礎（常見驗證/憑證 header 名稱與片段，例如 authorization、x-api-key、token、secret、password 和 credential）。

互動式 helper 會：

• 先設定 secrets.providers（env/file/exec，新增/編輯/移除）
• 讓你選取 openclaw.json 中支援的含 secret 欄位，加上一個 agent 範圍的 auth-profiles.json
• 可以直接在目標選擇器中建立新的 auth-profiles.json 對應
• 擷取 SecretRef 詳細資料（source、provider、id）
• 執行預檢解析
• 可以立即套用

Exec 注意事項：

• 除非設定 --allow-exec，否則預檢會略過 exec SecretRef 檢查。
• 如果你直接從 configure --apply 套用，且計畫包含 exec refs/providers，套用步驟也要保持設定 --allow-exec。

實用模式：

• openclaw secrets configure --providers-only
• openclaw secrets configure --skip-provider-setup
• openclaw secrets configure --agent <id>

configure 套用預設值：

• 從 auth-profiles.json 清除目標 providers 的相符靜態憑證
• 從 auth.json 清除舊版靜態 api_key 項目
• 從 <config-dir>/.env 清除相符的已知 secret 行

套用已儲存的計畫：

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

Exec 注意事項：

• 除非設定 --allow-exec，否則 dry-run 會略過 exec 檢查。
• 除非設定 --allow-exec，否則寫入模式會拒絕包含 exec SecretRefs/providers 的計畫。

如需嚴格目標/路徑合約詳細資訊和確切拒絕規則，請參閱 Secrets 套用計畫合約。