跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 會從多個來源讀取環境變數。規則是絕不覆寫現有值。

​
優先順序（最高 → 最低）

  1. 程序環境（Gateway 程序已從父層 shell/daemon 取得的內容）。
  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），只會套用缺少的預期鍵。
在使用預設狀態目錄的 Ubuntu 全新安裝中，OpenClaw 也會在全域 .env 之後，將 ~/.config/openclaw/gateway.env 視為相容性備援。如果兩個檔案都存在且內容不一致，OpenClaw 會保留 ~/.openclaw/.env 並印出警告。 如果設定檔完全缺失，步驟 4 會被略過；若已啟用，shell 匯入仍會執行。

​
設定中的 env 區塊

設定行內環境變數有兩種等效方式（兩者都不會覆寫）： 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

​
Shell 環境匯入

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}",
      },
    },
  },
}
完整詳細資訊請參閱設定：環境變數替換。

​
Secret refs 與 ${ENV} 字串

OpenClaw 支援兩種環境驅動模式：
  • 設定值中的 ${VAR} 字串替換。
  • SecretRef 物件（{ source: "env", provider: "default", id: "VAR" }），用於支援秘密參照的欄位。
兩者都會在啟用時從程序環境解析。SecretRef 詳細資訊記錄於秘密管理。

​
路徑相關環境變數

變數用途
OPENCLAW_HOME覆寫用於所有內部路徑解析的家目錄（~/.openclaw/、代理程式目錄、工作階段、憑證）。在以專用服務使用者執行 OpenClaw 時很有用。
OPENCLAW_STATE_DIR覆寫狀態目錄（預設為 ~/.openclaw）。
OPENCLAW_CONFIG_PATH覆寫設定檔路徑（預設為 ~/.openclaw/openclaw.json）。
OPENCLAW_INCLUDE_ROOTS目錄路徑清單，允許 $include 指令解析設定目錄外的檔案（預設：無 — $include 受限於設定目錄）。會展開波浪號。

​
日誌

變數用途
OPENCLAW_LOG_LEVEL覆寫檔案與主控台的日誌層級（例如 debug、trace）。優先於設定中的 logging.level 和 logging.consoleLevel。無效值會被忽略並顯示警告。
OPENCLAW_DEBUG_MODEL_TRANSPORT在 info 層級輸出目標式模型請求/回應時序診斷，而不啟用全域 debug 日誌。
OPENCLAW_DEBUG_MODEL_PAYLOAD模型負載診斷：summary、tools 或 full-redacted。full-redacted 有上限且會遮蔽，但可能包含提示/訊息文字。
OPENCLAW_DEBUG_SSE串流診斷：events 用於 first/done 時序，peek 則包含前五個已遮蔽的 SSE 事件。
OPENCLAW_DEBUG_CODE_MODEcode-mode 模型表面診斷，包括 provider-tool 隱藏與僅限 exec/wait 的強制執行。

​
OPENCLAW_HOME

設定後，OPENCLAW_HOME 會取代系統家目錄（$HOME / os.homedir()），用於所有內部路徑解析。這可為無頭服務帳號啟用完整的檔案系統隔離。 優先順序： OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir() 範例（macOS LaunchDaemon）： 
<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/user</string>
</dict>
OPENCLAW_HOME 也可以設為波浪號路徑（例如 ~/svc），使用前會透過 $HOME 展開。

​
nvm 使用者：web_fetch TLS 失敗

如果 Node.js 是透過 nvm 安裝（而不是系統套件管理器），內建的 fetch() 會使用 nvm 內建的 CA 儲存區，其中可能缺少現代根 CA（Let’s Encrypt 的 ISRG Root X1/X2、 DigiCert Global Root G2 等）。這會導致 web_fetch 在大多數 HTTPS 網站上因 "fetch failed" 而失敗。 在 Linux 上，OpenClaw 會自動偵測 nvm，並在實際啟動環境中套用修正：
  • openclaw gateway install 會將 NODE_EXTRA_CA_CERTS 寫入 systemd 服務環境
  • openclaw CLI 進入點會在 Node 啟動前，帶著已設定的 NODE_EXTRA_CA_CERTS 重新執行自身
手動修正（適用於較舊版本或直接 node ... 啟動）： 在啟動 OpenClaw 前匯出變數： 
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run
不要只依賴將此變數寫入 ~/.openclaw/.env；Node 會在程序啟動時讀取 NODE_EXTRA_CA_CERTS。

​
舊版環境變數

OpenClaw 只會讀取 OPENCLAW_* 環境變數。早期版本的舊版 CLAWDBOT_* 和 MOLTBOT_* 前綴會被靜默忽略。 如果 Gateway 程序啟動時仍設定了任何這些變數，OpenClaw 會輸出一則 Node 棄用警告（OPENCLAW_LEGACY_ENV_VARS），列出偵測到的 前綴與總數。請將舊版前綴替換為 OPENCLAW_ 來重新命名每個值 （例如 CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN）；舊名稱不會生效。

​
相關