密鑰管理

OpenClaw 支援可附加的 SecretRef，因此受支援的認證資訊不必以純文字形式存放在設定中。

執行階段模型

• 密鑰會在啟用期間立即解析至記憶體內的執行階段快照，而不是在請求路徑上延遲解析。
• 如果實際啟用的 SecretRef 無法解析，啟動會立即失敗。
• 重新載入採用不可分割的交換：全部成功，否則保留最後一個已知正常的快照。
• 違反原則（例如將 OAuth 模式的驗證設定檔與 SecretRef 輸入結合）時，啟用會在交換執行階段快照之前失敗。
• 執行階段請求只會讀取作用中的記憶體內快照。模型供應商的 SecretRef 認證資訊會以程序本機哨兵值的形式，經過驗證儲存空間與串流選項，直到送出程序為止。對外傳送路徑（Discord 回覆／討論串傳送、Telegram 動作傳送）也會讀取該快照，不會在每次傳送時重新解析參照。

如此可避免密鑰供應商中斷影響高頻請求路徑。

送出時注入（哨兵值）

對於由 SecretRef 支援的模型供應商認證資訊，OpenClaw 會在解析模型驗證時產生不透明的程序本機哨兵值。因此，驗證儲存空間、串流選項、SDK 設定、日誌、錯誤物件和大多數執行階段自省功能看到的會是類似 oc-sent-v1-... 的值，而非供應商認證資訊。受保護的模型 fetch 與受管理的本機供應商健康探測，會在每個請求離開程序之前，立即替換 URL 和標頭值中的已知哨兵值。

未知的哨兵值形式內容會在任何網路活動之前以封閉方式失敗。OpenClaw 會拒絕傳送請求，而不會將未解析的哨兵值轉送給供應商。已解析的密鑰值也會登錄為依精確值遮蔽日誌，作為縱深防禦措施。

供應商轉接器會使用其 SDK 支援的最末端注入點：

• 具有自訂 fetch 選項的 SDK 會接收 OpenClaw 的受保護 fetch，因此 SDK 會保留哨兵值。
• 不具自訂 fetch 選項的 SDK 會在建立用戶端之前立即解開哨兵值。由外掛擁有的供應商串流和代理程式測試框架，會在最終由核心擁有的交接點解開，因為這些傳輸不共用 OpenClaw 的受保護 fetch。

哨兵值可減少模型呼叫鏈中的純文字暴露，但不提供程序隔離。實際值仍存在於同一程序的記憶體中，並會出現在最終轉接器邊界。未透過 SecretRef 設定的一般環境認證資訊仍是純文字，不受此機制保護。

設定 OPENCLAW_SECRET_SENTINELS=off（也接受 0 或 false，不區分大小寫），可在事件應變或相容性疑難排解期間停用哨兵值產生。此終止開關不會停用依精確值登錄遮蔽的功能。

代理程式存取邊界

SecretRef 可防止認證資訊持久化至設定和產生的模型檔案，但不構成程序隔離邊界。如果純文字認證資訊仍留在磁碟上代理程式可讀取的路徑中，仍可透過檔案或 shell 工具讀取，繞過 API 層級的遮蔽。

對於將代理程式可存取檔案納入考量的正式環境部署，只有在符合下列所有條件時，才應將遷移視為完成：

• 受支援的認證資訊使用 SecretRef，而非純文字值。
• 已從 openclaw.json、auth-profiles.json、.env 和產生的 models.json 檔案中清除舊版純文字殘留。
• 遷移後，openclaw secrets audit --check 檢查結果無異常。
• 所有仍不受支援或會輪替的認證資訊，皆由作業系統隔離、容器隔離或外部認證資訊 Proxy 保護。

這正是稽核／設定／套用工作流程屬於安全遷移關卡，而不只是便利輔助工具的原因。

作用中介面篩選

只會在實際作用中的介面驗證 SecretRef：

• 已啟用的介面：未解析的參照會阻止啟動／重新載入。
• 非作用中介面：未解析的參照不會阻止啟動／重新載入；它們會發出非致命的 SECRETS_REF_IGNORED_INACTIVE_SURFACE 診斷。

閘道驗證介面診斷

在 gateway.auth.token、gateway.auth.password、gateway.remote.token 或 gateway.remote.password 上設定 SecretRef 時，閘道啟動／重新載入會以代碼 SECRETS_GATEWAY_AUTH_SURFACE 記錄介面狀態：

• active：SecretRef 是有效驗證介面的一部分，且必須成功解析。
• inactive：另一個驗證介面優先，或遠端驗證已停用／未作用。

日誌項目會包含作用中介面原則採用該狀態的原因。

初始設定參照預檢

在互動式初始設定中，選擇 SecretRef 儲存方式會在儲存前執行預檢驗證：

• 環境參照：驗證環境變數名稱，並確認設定期間可看到非空值。
• 供應商參照（file 或 exec）：驗證供應商選擇、解析 id，並檢查解析值的型別。
• 快速入門流程：當 gateway.auth.token 已是 SecretRef 時，初始設定會使用相同的立即失敗關卡，在探測／儀表板啟動之前解析它（適用於 env、file 和 exec 參照）。

驗證失敗時會顯示錯誤，並讓你重試。

SecretRef 合約

所有位置都使用同一種物件形式：

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

供應商設定

在 secrets.providers 下定義供應商：

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // or "singleValue"      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        args: ["--profile", "prod"],        passEnv: ["PATH", "VAULT_ADDR"],        jsonOnly: true,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

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

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

{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}

檔案支援的 API 金鑰

請勿在設定的 env 區塊中放置 file:... 字串。該區塊使用字面值且不會覆寫，因此絕不會在其中解析 file:...。

請改為在支援的認證資訊欄位上使用檔案 SecretRef：

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

對於 mode: "singleValue"，SecretRef id 為 "value"。對於 mode: "json"，請使用絕對 JSON 指標，例如 "/providers/xai/apiKey"。

如需瞭解接受 SecretRef 的欄位，請參閱 SecretRef 認證資訊介面。

Exec 整合範例

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // Homebrew 符號連結二進位檔所需        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: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // Homebrew 符號連結二進位檔所需        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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`無法剖析要求：${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass 結束，狀態為 ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // Homebrew 符號連結二進位檔所需        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" },      },    },  },}

MCP 伺服器環境變數

透過 plugins.entries.acpx.config.mcpServers 設定的 MCP 伺服器環境變數接受 SecretInput，使 API 金鑰和權杖不會出現在純文字設定中：

{  plugins: {    entries: {      acpx: {        enabled: true,        config: {          mcpServers: {            github: {              command: "npx",              args: ["-y", "@modelcontextprotocol/server-github"],              env: {                GITHUB_PERSONAL_ACCESS_TOKEN: {                  source: "env",                  provider: "default",                  id: "MCP_GITHUB_PAT",                },              },            },          },        },      },    },  },}

純文字字串值仍可使用。${MCP_SERVER_API_KEY} 等環境範本參照與 SecretRef 物件會在閘道啟用期間、MCP 伺服器程序產生之前解析。與其他 SecretRef 介面相同，只有在 acpx 外掛實際啟用時，未解析的參照才會阻止啟用。

沙箱 SSH 驗證資料

核心 ssh 沙箱後端也支援 SSH 驗證資料的 SecretRef：

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        ssh: {          target: "user@gateway-host:22",          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

執行階段行為：

• OpenClaw 會在沙箱啟用期間解析這些參照，而不是在每次 SSH 呼叫時才延遲解析。
• 解析後的值會寫入具有嚴格檔案權限 (0o600) 的暫存目錄，並用於產生的 SSH 設定。
• 如果實際使用的沙箱後端不是 ssh（或沙箱模式為 off），這些參照會保持非作用中狀態，且不會阻止啟動。

支援的認證資訊介面

SecretRef 認證資訊介面列出標準支援與不支援的認證資訊。

必要行為與優先順序

• 沒有參照的欄位：維持不變。
• 有參照的欄位：啟用期間在作用中介面上為必要項目。
• 如果同時存在純文字和參照，則在支援的優先順序路徑上以參照為優先。
• 遮蔽哨兵值 __OPENCLAW_REDACTED__ 保留供內部設定遮蔽／還原使用，若作為字面提交的設定資料，將遭到拒絕。

警告與稽核訊號：

• SECRETS_REF_OVERRIDES_PLAINTEXT（執行階段警告）
• REF_SHADOWED（當 auth-profiles.json 認證資訊優先於 openclaw.json 參照時的稽核發現）

Google Chat 相容性：serviceAccountRef 優先於純文字 serviceAccount；設定同層級的參照後，純文字值會被忽略。

啟用觸發條件

祕密啟用會在下列情況執行：

• 啟動（預先檢查加上最終啟用）
• 設定重新載入的熱套用路徑
• 設定重新載入的重新啟動檢查路徑
• 透過 secrets.reload 手動重新載入
• 閘道設定寫入 RPC 預先檢查（config.set / config.apply / config.patch），在保存編輯之前，檢查提交的設定承載資料內作用中介面的 SecretRef 是否可解析

啟用合約：

• 成功時會以不可分割的方式交換快照。
• 啟動失敗會中止閘道啟動。
• 執行階段重新載入失敗會保留最後已知正常的快照。
• 寫入 RPC 預先檢查失敗會拒絕提交的設定；磁碟設定與作用中的執行階段快照都會維持不變。
• 向輸出輔助函式／工具呼叫提供明確的單次頻道權杖，不會觸發 SecretRef 啟用；啟用點仍為啟動、重新載入，以及明確的 secrets.reload。

降級與復原訊號

在正常狀態之後，若重新載入時的啟用失敗，OpenClaw 會進入祕密降級狀態，並發出一次性系統事件與記錄程式碼：

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

行為：

• 降級：執行階段保留最近一次已知良好的快照。
• 復原：在下一次成功啟用後發出一次。
• 已處於降級狀態時若持續失敗，會記錄警告，但不會再次發出事件。
• 啟動時的快速失敗絕不會發出降級事件，因為執行階段從未進入啟用狀態。

命令路徑解析

命令路徑可透過閘道快照 RPC，選擇使用支援的 SecretRef 解析。大致分為兩種行為：

其他注意事項：

• 後端祕密輪替後的快照重新整理由 openclaw secrets reload 處理。
• 這些命令路徑使用的閘道 RPC 方法：secrets.resolve。

稽核與設定工作流程

預設操作流程：

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

重新稽核結果完全乾淨之前，請勿將遷移視為完成。如果稽核仍回報靜態儲存中的純文字值，即使執行階段 API 傳回的是遮蔽值，代理程式存取風險仍然存在。

如果你在 configure 期間儲存方案而非直接套用，請在重新稽核前使用 openclaw secrets apply --from <plan-path> 套用該已儲存的方案。

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

單向安全政策

安全模型：

• 進入寫入模式前，預檢必須成功。
• 提交前會驗證執行階段啟用狀態。
• 套用作業會使用不可分割的檔案取代來更新檔案，並在失敗時盡力還原。

舊版驗證相容性注意事項

對於靜態認證資訊，執行階段不再依賴純文字的舊版驗證儲存空間。

• 執行階段認證資訊來源是已解析的記憶體內快照。
• 發現舊版靜態 api_key 項目時會將其移除。
• OAuth 相關的相容性行為會分開處理。

Web UI 注意事項

部分 SecretInput 聯集型別使用原始編輯器模式會比表單模式更容易設定。

相關內容

• 驗證 - 驗證設定
• 命令列介面：祕密 - 命令列介面命令
• Vault SecretRef - HashiCorp Vault 供應商設定
• 環境變數 - 環境變數優先順序
• SecretRef 認證資訊介面 - 認證資訊介面
• 祕密套用方案合約 - 方案合約詳細資料
• 安全性 - 安全態勢