LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-03-07 22:44:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
069c495df630b49ad8e690da7b2ab3c6c6874706
moltbot/docs/help/environment.md
maweibin 98a03c490b Feat/logger support log level validation0222 (#23436) 
* 1、环境变量**：新增 `OPENCLAW_LOG_LEVEL`，可取值 `silent|fatal|error|warn|info|debug|trace`。设置后同时覆盖**文件日志**与**控制台**的级别，优先级高于配置文件。
2、启动参数**：在 `openclaw gateway run` 上新增 `--log-level <level>`，对该次进程同时生效于文件与控制台；未传时仍使用环境变量或配置文件。

* fix(logging): make log-level override global and precedence-safe

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
2026-02-22 11:15:13 +01:00

4.3 KiB
Raw Blame History

summary, read_when, title
summary read_when title
Where OpenClaw loads environment variables and the precedence order
You need to know which env vars are loaded, and in what order
You are debugging missing API keys in the Gateway
You are documenting provider auth or deployment environments
Environment Variables

Environment variables

OpenClaw pulls environment variables from multiple sources. The rule is never override existing values.

Precedence (highest → lowest)

  1. Process environment (what the Gateway process already has from the parent shell/daemon).
  2. .env in the current working directory (dotenv default; does not override).
  3. Global .env at ~/.openclaw/.env (aka $OPENCLAW_STATE_DIR/.env; does not override).
  4. Config env block in ~/.openclaw/openclaw.json (applied only if missing).
  5. Optional login-shell import (env.shellEnv.enabled or OPENCLAW_LOAD_SHELL_ENV=1), applied only for missing expected keys.

If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.

Config env block

Two equivalent ways to set inline env vars (both are non-overriding):

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

Shell env import

env.shellEnv runs your login shell and imports only missing expected keys:

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

Env var equivalents:

  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Env var substitution in config

You can reference env vars directly in config string values using ${VAR_NAME} syntax:

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

See Configuration: Env var substitution for full details.

Path-related env vars

Variable Purpose
OPENCLAW_HOME Override the home directory used for all internal path resolution (~/.openclaw/, agent dirs, sessions, credentials). Useful when running OpenClaw as a dedicated service user.
OPENCLAW_STATE_DIR Override the state directory (default ~/.openclaw).
OPENCLAW_CONFIG_PATH Override the config file path (default ~/.openclaw/openclaw.json).

Logging

Variable Purpose
OPENCLAW_LOG_LEVEL Override log level for both file and console (e.g. debug, trace). Takes precedence over logging.level and logging.consoleLevel in config. Invalid values are ignored with a warning.

OPENCLAW_HOME

When set, OPENCLAW_HOME replaces the system home directory ($HOME / os.homedir()) for all internal path resolution. This enables full filesystem isolation for headless service accounts.

Precedence: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Example (macOS LaunchDaemon):

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

OPENCLAW_HOME can also be set to a tilde path (e.g. ~/svc), which gets expanded using $HOME before use.

Related