OpenClaw Secrets 管理指南：告別設定檔中的明文憑證

你是否也曾擔心過，把 API 金鑰直接寫在設定檔裡會不小心 commit 到 GitHub？或者在多個環境切換時，手動修改憑證改到心累？處理憑證管理這件事，往往是開發流程中最讓人頭痛的小細節，既要保證安全，又不想讓設定變得太複雜。

OpenClaw 提供的 SecretRefs 功能就是為了幫你解決這個問題。它讓你不再需要把敏感資訊以 plaintext（明文）存放在設定檔中，而是透過引用（Reference）的方式來動態載入。

需要準備的東西

在開始之前，請確保你已經準備好：

OpenClaw 執行環境
想要管理的憑證（例如 OpenAI API 金鑰）
對應的儲存來源（環境變數、JSON 檔案或外部執行腳本）

Quick Start：5 分鐘設定 SecretRef

OpenClaw 的 SecretRef 採用統一的物件格式，無論你使用哪種來源，結構都長這樣：

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

1. 使用環境變數 (env)

這是最簡單的方式。如果你有一個環境變數叫 OPENAI_API_KEY：

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

注意：id 必須符合 ^[A-Z][A-Z0-9_]{0,127}$ 格式。

2. 使用 JSON 檔案 (file)

如果你想從特定的 JSON 檔案讀取憑證：

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

注意：id 必須是絕對 JSON pointer（以 / 開頭）。

3. 使用執行腳本 (exec)

如果你透過 Vault 或其他 CLI 工具獲取憑證：

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

運作邏輯

OpenClaw 在啟動（Startup）或重載（Reload）時會採取「積極解析」策略：

啟動即解析：秘密會在啟動時讀入記憶體快照，而不是等到請求發生時才讀取。
快速失敗：如果設定的 SecretRef 無法解析，啟動會直接失敗，確保不會帶著錯誤的憑證運行。
原子化更新：Reload 時若解析失敗，會保留上一次成功的快照，不會導致服務中斷。

Troubleshooting：常見問題與診斷

當你發現 SecretRef 沒有生效時，可以檢查 OpenClaw 的日誌，尋找以下診斷代碼：

1. 為什麼我的 SecretRef 被忽略了？

如果你看到 SECRETS_REF_IGNORED_INACTIVE_SURFACE，這代表該憑證目前處於「非活躍表面」。OpenClaw 只會驗證真正會被用到的憑證。例如：

該 Channel 或帳號已被禁用。
gateway.remote.enabled 為 false 時，相關的 remote token 會被標記為 inactive。
環境變數（如 OPENCLAW_GATEWAY_TOKEN）的優先級高於設定檔中的 SecretRef。

2. Gateway 認證診斷

針對 gateway.auth 或 gateway.remote 的憑證，日誌會明確顯示 SECRETS_GATEWAY_AUTH_SURFACE 狀態：

active: 該 SecretRef 是有效認證的一部分，必須解析成功。
inactive: 該 SecretRef 被忽略，可能是因為有更高優先級的環境變數，或相關功能未開啟。

3. Onboarding 預檢失敗

在互動式 Onboarding 過程中，OpenClaw 會先進行 Preflight 檢查。如果你的環境變數名稱不規範，或 JSON 檔案路徑不正確，系統會即時報錯並讓你重試。

想要更深入了解設定？或是遇到特定的配置難題？歡迎詢問我們的 AI Setup Assistant

下一步

處理專案的敏感資訊（Secrets）總是讓人頭大。你可能在本地開發時習慣用 `.env`，但到了生產環境又得對接複雜的 Vault 系統，這種不一致的體驗常常導致配置出錯。如果你也曾因為漏掉一個環境變數而導致服務啟動失敗，或者在管理不同來源的金鑰時感到混亂，這篇教學能幫你理清思路。

## 需要準備的東西

- 一個 OpenClaw 設定檔
- 你的 Secrets 來源（環境變數、本地 JSON 檔案或自定義的加密工具）

## 快速開始

要在 OpenClaw 中管理 Secrets，你需要在 `secrets.providers` 下定義不同的供應商。以下是一個包含三種常見來源的完整配置範例：

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

深入瞭解 Provider 類型

Env provider

這是最基礎的類型，直接從系統環境變數讀取資料。

你可以透過 allowlist 設定選用的允許清單。
如果環境變數缺失或內容為空，解析（resolution）將會失敗。

File provider

從本地路徑讀取檔案內容。

mode: “json”: 預期檔案內容為 JSON 物件，並將 id 當作指標（pointer）來解析。
mode: “singleValue”: 預期 ref id 為 "value"，並直接回傳整個檔案內容。
安全性: 檔案路徑必須通過擁有權與權限檢查。
Windows 注意事項: 如果路徑無法進行 ACL 驗證，解析會失敗。若你確定該路徑是安全的，可以在該 provider 設定 allowInsecurePath: true 來跳過檢查。

Exec provider

這是一個強大的功能，它會執行你指定的絕對路徑二進位檔（不透過 shell）。

預設情況下，command 必須指向一般檔案而非符號連結（symlink）。
如果你需要支援符號連結（例如 Homebrew 的路徑），請設定 allowSymlinkCommand: true。OpenClaw 會驗證解析後的目標路徑。
建議將 allowSymlinkCommand 與 trustedDirs（例如 ["/opt/homebrew"]）搭配使用。
支援設定 timeout、無輸出超時、輸出位元組限制、環境變數允許清單以及信任目錄。

請求格式 (stdin):

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

回應格式 (stdout):

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

錯誤處理 (選填):

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

疑難排解

Windows 上解析失敗: 如果你遇到 ACL 驗證錯誤，請檢查路徑權限，或在信任該路徑的前提下設定 allowInsecurePath: true。
執行檔找不到: 確保 command 使用的是絕對路徑。如果你使用套件管理員安裝的工具，記得檢查是否需要開啟 allowSymlinkCommand 並將路徑加入 trustedDirs。
環境變數抓不到: 檢查 allowlist 是否正確包含了該變數名稱，且該變數在執行環境中確實存在。
效能問題: 如果解析速度太慢，可以調整 resolution 下的 maxProviderConcurrency 或 maxBatchBytes 參數。

有任何設定上的疑問嗎？歡迎詢問 AI Setup Assistant 獲取即時協助。

下一步

每次處理 API key 或敏感資料時，最煩的就是要在安全性跟便利性之間找平衡。把祕鑰寫死在程式碼裡絕對是大忌，但手動設定環境變數又很瑣碎，尤其當你有好幾個專案要切換的時候。

如果你已經在使用 1Password、Vault 或 sops 這些工具，直接讓系統幫你執行指令來抓資料會輕鬆很多。這樣你就不必在本地儲存明文密鑰，也能確保開發環境的一致性，讓你的工作流程更乾淨。

What You’ll Need

1Password CLI, HashiCorp Vault CLI 或 sops
已安裝 Homebrew（若你的工具路徑在 /opt/homebrew）
對應的祕鑰存取權限與設定檔

Quick Start

透過 exec 整合，你可以直接呼叫外部 CLI 工具來獲取祕鑰。以下是幾種常見工具的配置範例，你可以依照你的需求選擇。

1Password CLI

這個範例會從 1Password 的個人金庫中讀取 OpenAI 的 API key。

{
  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" },
      },
    },
  },
}

HashiCorp Vault CLI

如果你偏好使用 Vault，可以透過 kv get 指令來抓取特定欄位，並傳遞必要的環境變數。

{
  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" },
      },
    },
  },
}

`sops`

對於習慣將加密檔案存放在專案中的開發者，sops 是一個非常靈活的選擇。

{
  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" },
      },
    },
  },
}

Troubleshooting

Homebrew 安裝的指令無法執行：如果你是透過 Homebrew 安裝 CLI 工具，請務必將 allowSymlinkCommand 設定為 true，因為 Homebrew 的執行檔通常是軟連結（symlinks）。
權限或環境變數錯誤：確保你在 passEnv 中加入了指令執行所需的變數。例如 Vault 需要 VAULT_ADDR 才能找到伺服器，而 sops 可能需要 SOPS_AGE_KEY_FILE 來進行解密。

想要更快速的設定體驗嗎？試試我們的 AI Setup Assistant。

What’s Next

處理憑證（Credentials）最煩人的就是要在安全性與便利性之間找平衡。如果你曾經因為在設定檔裡貼上明文金鑰而感到不安，或者在更新金鑰時不小心搞掛整個服務，你就會發現管理這些敏感資訊需要一套更可靠的機制。

OpenClaw 的 SecretRef 設計就是為了幫你處理這些麻煩事，讓你不需要手動管理那些會變動的祕密資訊。

需要準備的東西

SecretRef Credential Surface 中列出的支援路徑
運作中的 OpenClaw Gateway
已配置好的 auth-profiles.json 或 openclaw.json

快速開始

優先級測試：在設定檔中同時放置明文欄位與對應的 ref 欄位，系統會自動優先採用 ref。
手動更新：當你更新了後端的祕密資訊，執行 openclaw secrets reload 即可完成同步。
檢查狀態：使用 openclaw status 查看目前的憑證加載狀態。
驗證日誌：觀察是否出現 SECRETS_REF_OVERRIDES_PLAINTEXT 警告，確保你的設定符合預期。

核心行為與優先順序

在 OpenClaw 中，憑證的處理有一套明確的規則。如果你的欄位沒有設定 ref，它會保持不變；但只要設定了 ref，系統在激活（Activation）過程中就必須成功讀取該路徑。

當明文（Plaintext）和 ref 同時存在時，ref 在支援的路徑中擁有最高優先權。這裡有幾個關鍵的信號你需要留意：

SECRETS_REF_OVERRIDES_PLAINTEXT：這是一個運行時警告，提醒你 ref 已經覆蓋了明文數值。
REF_SHADOWED：這是一個審計發現，當 auth-profiles.json 的憑證優先於 openclaw.json 的 ref 時會觸發。

針對 Google Chat 的相容性，serviceAccountRef 會優先於明文的 serviceAccount。只要設定了同級的 ref，明文數值就會被直接忽略。

請注意，為了系統穩定性，Runtime 生成的憑證、輪轉中的憑證以及 OAuth refresh 資料目前刻意排除在唯讀的 SecretRef 解析範圍之外。

激活觸發器 (Activation Triggers)

Secret 的激活不會無緣無故發生，它主要綁定在以下四個時機：

啟動時：包含預檢（Preflight）以及最終激活。
設定檔熱重載 (Hot-apply)：不重啟服務直接套用。
設定檔重載檢查 (Restart-check)：確認重啟後的路徑有效。
手動觸發：透過 API 或指令執行 secrets.reload。

這背後有一套「激活合約」：如果成功，系統會原子化（Atomically）交換快照；如果啟動時失敗，Gateway 會直接放棄啟動；如果是運行中重載失敗，則會保留上一次已知的正常（Last-known-good）快照。

狀態信號：降級與恢復

當重載時激活失敗，但系統之前是健康狀態時，OpenClaw 會進入「降級（Degraded）」狀態。你會在日誌中看到以下代碼：

SECRETS_RELOADER_DEGRADED：進入降級狀態，運行時保留最後一次成功的快照。
SECRETS_RELOADER_RECOVERED：在下一次成功激活後發出，表示狀態已恢復。

如果系統已經處於降級狀態且持續失敗，它只會記錄警告日誌，不會重複發送事件。另外，啟動時的 Fail-fast 失敗不會觸發降級事件，因為運行時從未進入激活狀態。

CLI 命令路徑解析

不同的命令對 SecretRef 的容忍度不同，主要分為兩類行為：

1. 嚴格模式 (Strict)

像是 openclaw memory（遠端記憶體路徑）或 openclaw qr --remote。這些命令會直接從活動快照讀取，如果需要的 SecretRef 無法使用，命令會直接報錯失敗（Fail fast）。

2. 唯讀模式 (Read-only)

包含 openclaw status、openclaw status --all、openclaw channels status、openclaw channels resolve 以及唯讀的診斷或修復流程。

這些命令的行為比較彈性：

優先從 Gateway 的活動快照讀取。
如果 Gateway 解析不完整或無法連線，它們會嘗試針對特定命令介面進行本地回退（Local fallback）。
如果還是抓不到 SecretRef，命令會繼續執行並輸出「已配置但在此命令路徑不可用」的診斷訊息，而不會直接中斷。

這種降級行為僅限於本地命令，不會削弱運行時啟動、重載或訊息發送/驗證路徑的安全性。

疑難排解

啟動失敗：檢查所有定義的 SecretRef 是否在啟動時都能正確存取，啟動失敗會導致 Gateway 無法開啟。
憑證未更新：如果你在後端輪轉了祕密資訊，記得執行 openclaw secrets reload，因為快照更新需要手動或透過特定觸發器觸發。
看到 REF_SHADOWED：檢查你的 auth-profiles.json，確保沒有意外覆蓋了 openclaw.json 中的 ref 設定。
命令輸出顯示「Unavailable」：這通常發生在唯讀命令無法存取 Gateway 快照時，請確認 Gateway 是否正常運作或本地權限是否正確。

如果你還有其他設定上的疑問，可以隨時詢問 AI Setup Assistant。

下一步

SecretRef Credential Surface

每次在專案裡搜尋 API_KEY 時，是不是總擔心哪裡漏掉了明文？或者在 .env 跟各種 json 設定檔之間跳來跳去，搞不清楚到底哪份設定才是有效的？管理 Secrets 往往是開發中最容易出錯且讓人焦慮的一環。

OpenClaw 提供了一套完整的工具鏈，幫你從手動管理明文轉向自動化的 Secret 引用模式，確保你的金鑰不會意外出現在版本控制系統中。

需要準備的東西

安裝並配置好 OpenClaw CLI
專案中包含 openclaw.json 或 auth-profiles.json 等設定檔
需要被保護的 API 金鑰或憑證

快速開始

這是最推薦的標準操作流程，只需要三行指令就能完成從檢查到配置的循環：

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

深入了解 `secrets audit`

這個指令會掃描你的工作目錄，找出潛在的安全風險。它會檢查以下內容：

靜態存儲的明文數值：掃描 openclaw.json, auth-profiles.json, .env 以及自動產生的 agents/*/agent/models.json。
Header 殘留物：在產生的 models.json 中，檢查是否存在敏感的 Provider Header。
未解析的引用：找出那些定義了但無法正確獲取的 Secret 引用。
優先級遮蔽 (Precedence shadowing)：例如 auth-profiles.json 的設定覆蓋了 openclaw.json 中的引用。
舊版殘留：檢查是否存在 auth.json 或 OAuth 提醒等遺留檔案。

關於 Header 殘留物的偵測，OpenClaw 使用了名稱啟發式演算法，會自動識別常見的認證關鍵字，例如 authorization, x-api-key, token, secret, password 以及 credential。

使用 `secrets configure` 進行配置

這是一個互動式的輔助工具，引導你完成 Secret 的遷移：

配置供應商：優先設定 secrets.providers（支援 env, file, exec 的新增、編輯或刪除）。
選擇欄位：讓你選擇 openclaw.json 或特定 Agent 作用域下 auth-profiles.json 中支援 Secret 的欄位。
建立對應：可以直接在目標選擇器中建立新的 auth-profiles.json 對應。
捕獲 SecretRef 詳情：設定 source, provider 與 id。
預檢解析：在套用前先執行 Preflight 檢查。
立即套用：確認無誤後直接寫入設定。

如果你有特定需求，可以使用以下模式：

openclaw secrets configure --providers-only：只設定供應商。
openclaw secrets configure --skip-provider-setup：跳過供應商設定，直接進入欄位配置。
openclaw secrets configure --agent <id>：針對特定 Agent 進行配置。

當你執行 configure 套用變更時，OpenClaw 會自動執行清理動作：從 auth-profiles.json 中擦除匹配的靜態憑證、刪除 auth.json 中的舊版 api_key，並清理 .env 檔案中已知的 Secret 行。

執行 `secrets apply`

如果你已經有預先儲存好的計畫，可以使用 apply 指令：

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

關於目標路徑的嚴格契約與拒絕規則，請參考 Secrets Apply Plan Contract。

單向安全政策

OpenClaw 故意不設計寫入回滾備份的功能，因為這會導致歷史明文 Secret 再次被存回硬碟。

我們的安全模型包含以下特點：

強制預檢：在進入寫入模式前，Preflight 解析必須完全成功。
原子化操作：使用原子化檔案替換（Atomic file replacement）來更新設定，若失敗則會嘗試最佳還原，並在提交前驗證 Runtime 啟動狀態。

舊版認證相容性說明

對於靜態憑證，現在的 Runtime 已經不再依賴明文的舊版認證儲存空間：

Runtime 的憑證來源完全取決於記憶體中的解析快照。
發現舊版的 api_key 條目時會自動擦除。
OAuth 相關的相容行為則保持獨立處理。

Web UI 小提示：某些複雜的 SecretInput 聯合類型，在 Web 介面的「原始編輯模式 (Raw editor mode)」下會比「表單模式 (Form mode)」更容易配置。

疑難排解

稽核發現明文殘留：請執行 openclaw secrets configure 並按照引導將明文轉換為 SecretRef。
優先級衝突：如果發現 auth-profiles.json 遮蔽了你的設定，請檢查該檔案中的 priority 設定或刪除重複的靜態定義。
Header 偵測誤判：由於是基於名稱啟發式偵測，如果你的自定義 Header 包含 token 等字眼，可能會被標記為殘留物，請手動確認並清理。
Preflight 失敗：請確保你的 secrets.providers 設定正確，且對應的環境變數或檔案路徑在目前環境下是可存取的。

想要針對你的特定環境進行配置？試試 AI Setup Assistant。

下一步

查看所有 CLI 指令：secrets
深入瞭解計畫契約：Secrets Apply Plan Contract
憑證欄位參考：SecretRef Credential Surface
認證設定指南：Authentication
安全架構說明：Security
環境變數優先級：Environment Variables

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。

OpenClaw Secrets 管理指南：告別設定檔中的明文憑證

需要準備的東西

Quick Start：5 分鐘設定 SecretRef

1. 使用環境變數 (env)

2. 使用 JSON 檔案 (file)

3. 使用執行腳本 (exec)

運作邏輯

Troubleshooting：常見問題與診斷

1. 為什麼我的 SecretRef 被忽略了？

2. Gateway 認證診斷

3. Onboarding 預檢失敗

下一步

深入瞭解 Provider 類型

Env provider

File provider

Exec provider

疑難排解

下一步

What You’ll Need

Quick Start

1Password CLI

HashiCorp Vault CLI

sops

Troubleshooting

What’s Next

需要準備的東西

快速開始

核心行為與優先順序

激活觸發器 (Activation Triggers)

狀態信號：降級與恢復

CLI 命令路徑解析

1. 嚴格模式 (Strict)

2. 唯讀模式 (Read-only)

疑難排解

下一步

需要準備的東西

快速開始

深入了解 secrets audit

使用 secrets configure 進行配置

執行 secrets apply

單向安全政策

舊版認證相容性說明

疑難排解

下一步

還是卡住了？

`sops`

深入了解 `secrets audit`

使用 `secrets configure` 進行配置

執行 `secrets apply`