OpenClaw Environment Variables 完全指南

管理 API key 和各種路徑設定總是讓人頭痛。有時候你在 shell 設好了變數，結果程式跑起來卻抓不到；或者你想在不同專案切換設定，卻發現全域變數一直來攪局，搞得開發環境一團亂。

OpenClaw 的環境變數機制設計得很直覺，核心原則只有一個：絕對不覆蓋已存在的值。這篇文章會帶你理清它的載入邏輯，讓你精準掌控每個設定。

需要準備的東西

• OpenClaw Gateway
• openclaw.json 配置文件（選配）

快速開始

OpenClaw 會從多個來源抓取環境變數，順序非常重要。以下是優先順序（由高到低）：

1. Process environment: 你目前的 shell 或 daemon 進程中已經存在的變數。
2. 當前目錄的 .env: 使用 dotenv 預設載入，但不會覆蓋已有的值。
3. 全域 .env: 位於 ~/.openclaw/.env（即 $OPENCLAW_STATE_DIR/.env），同樣不覆蓋已有值。
4. Config env 區塊: 寫在 ~/.openclaw/openclaw.json 裡的設定，僅在變數缺失時套用。
5. 選配的 login-shell 匯入: 透過 env.shellEnv.enabled 開啟，僅補足缺失的 key。

在 Config 中設定變數

你有兩種等價的方式在 openclaw.json 裡設定環境變數：

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

使用變數替換

你可以在設定檔的字串中直接引用環境變數，語法是 ${VAR_NAME}：

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

進階路徑設定

如果你需要將 OpenClaw 作為獨立服務執行，或是想隔離檔案系統，這幾個變數會幫上大忙：

變數	用途
OPENCLAW_HOME	覆蓋所有內部路徑解析的家目錄（預設 ~/.openclaw/）。
OPENCLAW_STATE_DIR	覆蓋狀態目錄（預設 ~/.openclaw）。
OPENCLAW_CONFIG_PATH	覆蓋設定檔路徑（預設 ~/.openclaw/openclaw.json）。

關於 OPENCLAW_HOME

當你設定了 OPENCLAW_HOME，它會取代系統的 $HOME。這對於 headless 服務帳號非常有用。

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

macOS LaunchDaemon 範例：

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

疑難排解

為什麼我的設定檔變數沒生效？

請記住 OpenClaw 永不覆蓋。如果你在 shell 或是 .env 檔案中已經定義了同名的變數，openclaw.json 裡的設定就會被忽略。

Shell 環境匯入失敗或太慢？

如果你啟用了 env.shellEnv，可以調整超時設定：

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

或者直接設定環境變數 OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

---

還有疑問嗎？試試我們的 AI Setup Assistant 獲取即時協助。

下一步

• Gateway configuration
• FAQ: env vars and .env loading
• Models overview