環境變數

OpenClaw 從多個來源讀取環境變數。核心規則是絕不覆蓋已有值。

優先順序（從高到低）

1. 處理程序環境變數（閘道處理程序從父 shell/守護程式繼承的變數）。
2. 當前工作目錄的 .env 檔案（dotenv 預設行為；不會覆蓋已有值）。
3. 全域 .env 檔案，位於 ~/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env；不會覆蓋已有值）。
4. 組態中的 env 區塊，位於 ~/.openclaw/openclaw.json（僅在變數缺失時套用）。
5. 選用的登入 shell 匯入（env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1），僅對缺失的預期金鑰套用。

如果組態檔完全不存在，步驟 4 會被跳過；shell 匯入在啟用時仍會執行。

組態中的 env 區塊

兩種等效方式設定行內環境變數（兩者都不會覆蓋）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Shell env 匯入

env.shellEnv 執行你的登入 shell 並僅匯入缺失的預期金鑰：

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

等效環境變數：

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

執行時期注入的環境變數

OpenClaw 也會在產生的子處理程序中注入上下文標記：

• OPENCLAW_SHELL=exec：透過 exec 工具執行的命令會設定此值。
• OPENCLAW_SHELL=acp：ACP 執行時期後端處理程序產生時設定（例如 acpx）。
• OPENCLAW_SHELL=acp-client：openclaw acp client 產生 ACP 橋接處理程序時設定。
• OPENCLAW_SHELL=tui-local：本機 TUI ! shell 命令設定。

這些是執行時期標記（非必要的使用者組態）。可在 shell/profile 邏輯中使用，以套用特定上下文的規則。

UI 環境變數

• OPENCLAW_THEME=light：當終端機背景為淺色時，強制使用淺色 TUI 調色盤。
• OPENCLAW_THEME=dark：強制使用深色 TUI 調色盤。
• COLORFGBG：如果終端機匯出此值，OpenClaw 會利用背景色提示自動選擇 TUI 調色盤。

組態中的環境變數替換

你可以使用 ${VAR_NAME} 語法在組態字串值中直接參考環境變數：

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

詳見 組態：環境變數替換。

SecretRef 與 ${ENV} 字串

OpenClaw 支援兩種基於環境變數的模式：

• 組態值中的 ${VAR} 字串替換。
• SecretRef 物件（{ source: "env", provider: "default", id: "VAR" }），用於支援密鑰參考的欄位。

兩者都在啟用時從處理程序環境解析。SecretRef 詳情請參閱 密鑰管理。

路徑相關環境變數

記錄

OPENCLAW_HOME

設定後，OPENCLAW_HOME 會取代系統主目錄（$HOME / os.homedir()）用於所有內部路徑解析。這使 headless 服務帳戶能夠完全隔離檔案系統。

優先順序： OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

範例（macOS LaunchDaemon）：

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

OPENCLAW_HOME 也可以設定為波浪號路徑（例如 ~/svc），使用前會透過 $HOME 展開。

相關內容

• 閘道組態
• 常見問題：環境變數和 .env 載入
• 模型概覽