English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Diagnostics

環境變數

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 區塊

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

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

Shell 環境匯入

env.shellEnv 會執行你的登入 shell，並且只匯入缺少的預期鍵：

json5
{  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} 語法，在設定字串值中直接參照環境變數：

json5
{  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_MODE code-mode 模型表面診斷，包括 provider-tool 隱藏與僅限 exec/wait 的強制執行。

OPENCLAW_HOME

設定後，OPENCLAW_HOME 會取代系統家目錄（$HOME / os.homedir()），用於所有內部路徑解析。這可為無頭服務帳號啟用完整的檔案系統隔離。

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

範例（macOS LaunchDaemon）：

xml
<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 前匯出變數：

bash
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw 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）；舊名稱不會生效。

相關

Was this useful?