設定 OpenClaw 環境變數：完整指南與常見問題排除

每次在本地端跑得好好的，一換到背景服務或 CI 環境，環境變數就莫名其妙抓不到，這種抓鬼過程真的很煩人。搞清楚工具怎麼處理環境變數，能幫你省下大把除錯時間。

Environment Variables

OpenClaw 如何載入與管理環境變數。

---

OpenClaw 如何載入環境變數？

OpenClaw 會從父程序（shell, launchd/systemd, CI 等）讀取環境變數，並額外載入：

• 當前工作目錄下的 .env
• 全域備用檔案 ~/.openclaw/.env（也就是 $OPENCLAW_STATE_DIR/.env）

這兩個 .env 檔案都不會覆蓋已經存在的環境變數。

你也可以在設定檔中定義內嵌的環境變數（僅在程序環境變數缺失時生效）：

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

---

「我透過服務啟動 Gateway 後，環境變數就消失了。」該怎麼辦？

兩個常見的解法：

1. 把缺失的 key 放到 ~/.openclaw/.env，這樣即使服務沒有繼承你的 shell 環境，也能讀到它們。

2. 開啟 shell 匯入功能（這是一個為了方便而設計的可選功能）：

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

這會執行你的 login shell 並僅匯入缺失的預期 key（絕不覆蓋）。對應的環境變數為：OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

---

我設定了 COPILOT_GITHUB_TOKEN，但模型狀態顯示「Shell env: off」，為什麼？

openclaw models status 報告的是 shell 環境匯入 是否已啟用。「Shell env: off」並不代表你的環境變數不見了 —— 它只是代表 OpenClaw 不會自動載入你的 login shell。

如果 Gateway 是作為服務（launchd/systemd）執行，它不會繼承你的 shell 環境。

可以嘗試以下其中一種方法來修復：

1. 將 token 放入 ~/.openclaw/.env
2. 啟用 shell 匯入（env.shellEnv.enabled: true）
3. 將它加入你的設定檔 env 區塊

接著重啟 Gateway：

openclaw gateway restart
openclaw models status

Copilot token 會從 COPILOT_GITHUB_TOKEN 讀取（也會讀取 GH_TOKEN / GITHUB_TOKEN）。

---

需要更多協助嗎？試試我們的 AI Setup Assistant。

下一步

• Gateway 配置指南
• 模型設定教學