环境变量

OpenClaw 从多个来源获取环境变量。常规规则是绝不覆盖已有值。对于 OpenClaw 安装的 systemd 服务，全局 .env 只能替换 OpenClaw 记录为受管（managed）的服务值。运维人员自有服务值仍然优先。

工作区 .env 文件是较低可信度的来源：在应用优先级之前，OpenClaw 会忽略来自工作区 .env 的提供方凭证和受保护的运行时控制项。

Systemd 启动时会保留配置引用的受管进程值，包括 $include 文件中的 ${VAR} 和 $VAR SecretRef 简写形式。这也涵盖运维人员通过 EnvironmentFile= 提供的值。如果某个受管值既不在可信 dotenv 文件中，也不在当前配置引用中，则会从 Gateway 进程环境中移除。

优先级（从高到低）¶

1. 进程环境（Gateway 进程从父 shell/守护进程继承的现有值）。
2. 当前工作目录下的 .env（dotenv 默认位置）。它不会覆盖已有值。OpenClaw 会忽略此文件中的提供方凭证和受保护的运行时控制项。
3. 全局 .env，位于 ~/.openclaw/.env，也称为 $OPENCLAW_STATE_DIR/.env。建议用于存放提供方 API 密钥。它不会覆盖已有值，但记录的 OpenClaw 受管 systemd 服务值除外。
4. 配置 env 块，位于 ~/.openclaw/openclaw.json（仅在缺失时应用）。
5. 可选的登录 shell 导入（env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1），仅对缺失的预期键应用。

在使用默认状态目录的全新 Ubuntu 安装中，OpenClaw 也会读取 ~/.config/openclaw/gateway.env。该文件是全局 .env 之后的兼容性回退。如果两个文件同时存在且内容不一致，OpenClaw 保留 ~/.openclaw/.env 并打印警告。

如果配置文件完全缺失，则跳过第 4 步。若已启用，shell 导入仍会运行。

支持的运维人员可见变量¶

以下变量是面向运维人员的受支持环境变量契约。未记录的 OPENCLAW_* 变量属于内部实现细节，可能随时消失，恕不另行通知。

路径与实例¶

OPENCLAW_HOME¶

设置后，OPENCLAW_HOME 会替换系统 home 目录（$HOME / os.homedir()），用于 OpenClaw 内部路径默认值。这包括默认状态目录、配置路径、代理目录、凭证、安装器新手引导工作区，以及 openclaw update --channel dev 使用的默认开发检出目录。

OPENCLAW_HOME 不会授予对操作系统账户原生 Gateway 服务的所有权。Gateway 服务管理命令会将重定位的 home 视为隔离状态。当需要独立的原生服务身份时，请使用操作系统账户 home 和命名 profile。

优先级： OPENCLAW_HOME > $HOME > USERPROFILE > Android 上 Termux PREFIX home 回退 > os.homedir()

空值以及字面字符串 undefined 和 null（去除首尾空白后）会被视为未设置。此时 CLI 的 home 路径显示使用 ~；有效的覆盖值则使用 $OPENCLAW_HOME。

示例（macOS LaunchDaemon）：

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

OPENCLAW_HOME 也可以设置为波浪号路径（例如 ~/svc），在使用前会通过相同的操作系统 home 回退链进行展开。

显式路径变量（如 OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH 和 OPENCLAW_GIT_DIR）仍然优先。操作系统账户任务（如 shell 启动文件检测、包管理器设置和宿主机 ~ 展开）可能仍会使用真实的系统 home。

临时编译缓存¶

打包版 OpenClaw 在设置了 NODE_COMPILE_CACHE 时使用 NODE_COMPILE_CACHE/openclaw/<version>/<build>，否则使用操作系统临时目录下的 node-compile-cache/openclaw。子进程复用相同的构建命名空间。源代码检出目录保留其现有的禁用缓存策略。

编译缓存引导属主会在一个后台工作进程中启动尽力而为的维护，该进程不会让 CLI 命令保持运行。Node 权限模式会跳过此维护，因为工作进程不继承其文件系统限制；缓存条目会一直保留，直到被无限制的调用或运维人员移除。清理在命令退出时停止；只有长时间运行的进程才有时间让其完成。它会将已取代的构建目录作为整体移除。最多每小时一次，或在淘汰另一个构建之后，它会移除超过七天的字节码，并将当前缓存裁剪至 512 MiB，优先删除最旧的文件。这是维护目标而非硬盘配额：并发写入以及在清理完成前退出的进程可能会暂时超过该限制。中断的维护在一小时后可再次尝试。位于 openclaw 子树之外的其他应用缓存会被保留。

Gateway 和身份验证¶

提供商凭据¶

核心和内置提供商插件识别以下凭据和提供商选择变量。当需要作用域凭据而不是一个进程级值时，请优先使用各提供商的配置或 SecretRef 字段。

AI_GATEWAY_API_KEY, ANTHROPIC_ADMIN_API_KEY, ANTHROPIC_ADMIN_KEY, ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, ARCEEAI_API_KEY, AZURE_OPENAI_API_KEY, AZURE_SPEECH_API_KEY, AZURE_SPEECH_KEY, AZURE_SPEECH_REGION, BASETEN_API_KEY, BRAVE_API_KEY, BYTEPLUS_API_KEY, BYTEPLUS_SEED_SPEECH_API_KEY, CEREBRAS_API_KEY, CHUTES_API_KEY, CHUTES_OAUTH_TOKEN, CLAWROUTER_API_KEY, CLOUDFLARE_AI_GATEWAY_API_KEY, CODEX_API_KEY, COHERE_API_KEY, COMFY_API_KEY, COMFY_CLOUD_API_KEY, COPILOT_GITHUB_TOKEN, DASHSCOPE_API_KEY, DEEPGRAM_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY, ELEVENLABS_API_KEY, EXA_API_KEY, FAL_API_KEY, FAL_KEY, FEATHERLESS_API_KEY, FIRECRAWL_API_KEY, FIREWORKS_API_KEY, FISH_API_KEY, FISH_AUDIO_API_KEY, GCLOUD_PROJECT, GEMINI_API_KEY, GMI_API_KEY, GOOGLE_API_KEY, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_API_KEY, GOOGLE_CLOUD_LOCATION, GOOGLE_CLOUD_PROJECT, GRADIUM_API_KEY, GROQ_API_KEY, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, INWORLD_API_KEY, KILOCODE_API_KEY, KIMICODE_API_KEY, KIMI_API_KEY, LITELLM_API_KEY, LLAMA_SERVER_API_KEY, LM_API_TOKEN, LONGCAT_API_KEY, MINIMAX_API_KEY, MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY, MINIMAX_OAUTH_TOKEN, MISTRAL_API_KEY, MODELSTUDIO_API_KEY, MODEL_API_KEY, MOONSHOT_API_KEY, NOVITA_API_KEY, NVIDIA_API_KEY, OLLAMA_API_KEY, OPENAI_ADMIN_KEY, OPENAI_API_KEY, OPENCODE_API_KEY, OPENCODE_ZEN_API_KEY, OPENROUTER_API_KEY, PARALLEL_API_KEY, PERPLEXITY_API_KEY, PIXVERSE_API_KEY, QIANFAN_API_KEY, QWEN_API_KEY, QWEN_TOKEN_PLAN_API_KEY, RUNWAYML_API_SECRET, RUNWAY_API_KEY, SENSEAUDIO_API_KEY, SGLANG_API_KEY, SPEECH_KEY, SPEECH_REGION, STEPFUN_API_KEY, SYNTHETIC_API_KEY, TAVILY_API_KEY, TOGETHER_API_KEY, TOKENHUB_API_KEY, TOKENPLAN_API_KEY, VENICE_API_KEY, VLLM_API_KEY, VOLCANO_ENGINE_API_KEY, VOLCENGINE_TTS_API_KEY, VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOYAGE_API_KEY, VYDRA_API_KEY, XAI_API_KEY, XIAOMI_API_KEY, XIAOMI_TOKEN_PLAN_API_KEY, XI_API_KEY, ZAI_API_KEY, 以及 Z_AI_API_KEY。

已安装的第三方插件可能在其插件清单中声明额外的凭据变量。这些变量是声明它们的插件的契约，而不是核心 OpenClaw 变量。

日志和诊断¶

功能和运行时开关¶

文件系统观察¶

配置热重载、Skills 刷新、内存索引以及开发监视监督进程使用 @openclaw/fs-safe/watch。现有的 CHOKIDAR_* 变量名称仍然受支持，适用于 Docker、虚拟机以及其他需要观察偏好的部署：

在 Linux、macOS 和 Windows 上的 Node.js 支持原生事件。在 auto 模式下，Bun 以及没有原生后端的运行时使用轮询，并使用与显式轮询相同的 CHOKIDAR_INTERVAL 设置。原生事件保留 fs-safe 的 30 秒协调间隔。无效或非正数的轮询间隔会使用 100 ms；更大的间隔会被限制在 2147483647 ms。

恢复机制仍因所有者而异。配置热重载会使用其现有退避策略重试失败的订阅。当 CHOKIDAR_USEPOLLING 未设置时，原生监视失败在这些重试之后还可以触发一个新的轮询订阅。显式覆盖会保留现有重试限制。当原生监视容量耗尽（watch-limit）时，内存索引会切换到搜索时刷新。每个 Memory 订阅每次扫描最多允许 1,000,000 个目录和 1,000,000 个检查条目，包括被排除的条目。更大的目录树在观察重试耗尽后也会回退到搜索时刷新。容量耗尽后，Skills 会在 agent 准备期间刷新，如果观察失败，开发监督进程会停止其子进程。

提供商凭据和工作区 .env¶

不要仅将提供商 API 密钥保存在工作区 .env 中。OpenClaw 会阻止工作区 .env 文件中的大量提供商凭据和端点重定向密钥，包括所有已知的提供商身份验证环境变量（例如 GEMINI_API_KEY、GOOGLE_API_KEY、XAI_API_KEY、MISTRAL_API_KEY、GROQ_API_KEY、DEEPSEEK_API_KEY、PERPLEXITY_API_KEY、BRAVE_API_KEY、TAVILY_API_KEY、EXA_API_KEY、FIRECRAWL_API_KEY），以及任何以 _API_HOST、_BASE_URL、_ENDPOINT 或 _HOMESERVER 结尾的密钥，还有整个 OPENCLAW_*、CLAWHUB_*、ANTHROPIC_API_KEY_* 和 OPENAI_API_KEY_* 命名空间。

请改用以下受信任来源之一来提供提供商凭据：

• Gateway 进程环境，例如 shell、launchd/systemd 单元、容器 secret 或 CI secret。
• 位于 ~/.openclaw/.env 或 $OPENCLAW_STATE_DIR/.env 的全局运行时 dotenv 文件。
• ~/.openclaw/openclaw.json 中的配置 env 块。
• 当启用 env.shellEnv.enabled 或 OPENCLAW_LOAD_SHELL_ENV=1 时，可选的登录 shell 导入。

如果你之前仅将提供商密钥或端点路由值保存在工作区 .env 中，请将它们移动到上述受信任来源之一。工作区 .env 仍可提供普通项目变量，只要它们不是凭据、端点重定向、主机覆盖或 OPENCLAW_* 运行时控制。

请参阅 工作区 .env 文件 了解安全原因。

配置 env 块¶

在 env.vars 下设置内联环境变量（值不会覆盖已有值）：

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

配置 env.vars 块仅接受字面字符串值。它不会展开 file:... 值。例如，XAI_API_KEY: "file:secrets/xai-api-key.txt" 会作为该确切字符串传递给提供商。

对于基于文件的提供商密钥，请在支持它的凭据字段上使用 SecretRef：

{
  secrets: {
    providers: {
      xai_key_file: {
        source: "file",
        path: "~/.openclaw/secrets/xai-api-key.txt",
        mode: "singleValue",
      },
    },
  },
  models: {
    providers: {
      xai: {
        apiKey: { source: "file", provider: "xai_key_file", id: "value" },
      },
    },
  },
}

有关支持的字段，请参阅 密钥管理 和 SecretRef 凭据接口。

Shell 环境变量导入¶

env.shellEnv 会运行你的登录 shell，并只导入缺失的预期键：

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

环境变量等价项：

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000（默认 15000）

对于 Bash，导入会使用交互式登录 shell（bash -lic），以便在登录启动文件运行之前初始化 PS1。Bash 会读取 /etc/profile 以及第一个可用的用户登录配置文件（~/.bash_profile、~/.bash_login 或 ~/.profile）。许多登录配置文件还会 source ~/.bashrc。请保持这些文件安静且执行范围有限，因为它们的输出、长时间运行的任务或失败可能影响 OpenClaw 启动。其他 shell 使用非交互式登录启动（-l -c）。探测会在其自己的会话中运行，并与你的终端分离，因此启动文件没有作业控制，也无法接管运行 OpenClaw 的终端。这种交互式 Bash 模式仅限于显式 shell 环境变量导入。普通 Gateway 命令期间自动可执行文件 PATH 发现仍为非交互式。

成功的探测会被缓存。如果探测失败，下一次 shell 环境或 PATH 查找会重试。

Exec shell 快照¶

在非 Windows Gateway 主机上，bash 和 zsh 的 exec 命令默认使用启动快照。在 Gateway 进程环境中设置 OPENCLAW_EXEC_SHELL_SNAPSHOT=0 可禁用此路径。值 false、no 和 off 也会禁用它。每次调用的 exec.env 值无法切换快照或重定向快照缓存。

运行时注入的环境变量¶

Gateway 端口监听器诊断和锁所有者身份探测会以受限环境运行原生工具，该环境包含可执行文件路径、操作系统引导和账户目录、临时目录，以及已知的区域设置和时区设置。这些子进程不会继承 provider 凭据、应用 token、代理、运行时注入变量或任意应用设置。此边界保持父环境以及常规 agent、Gateway 和 updater 负载环境不变。

OpenClaw 还会向生成的子进程注入上下文标记：

• OPENCLAW_SHELL=exec：为通过 exec 工具运行的命令设置。
• OPENCLAW_SHELL=acp-client：当 openclaw acp client 生成 ACP 桥接进程时设置。
• OPENCLAW_SHELL=tui-local：为本地 TUI ! shell 命令设置。
• OPENCLAW_CLI=1：为 CLI 入口点生成的子进程设置。

这些是运行时标记（不是必需的用户配置）。它们可用于 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}",
      },
    },
  },
}

缺失或空变量会保持可见为 ${VAR_NAME}，并发出警告。需要该值的消费者会将其视为不可用。当意图是字面量 ${VAR_NAME} 文本时，请使用 $${VAR_NAME}。

完整详情，请参阅 配置：环境变量替换。

这适用于 openclaw.json 中的字符串值。它也适用于 openclaw.json 通过 $include 引入的任何文件。include 情况之所以有效，是因为替换在 include 解析后对整个配置树运行。OpenClaw 的 dotenv 加载器不会展开环境变量值。例如，运行时 .env 文件中的 OPENCLAW_WORKSPACE_DIR=${XDG_CONFIG_HOME}/workspace 在 OpenClaw 加载时保持字面量。

由于 OpenClaw 不会展开这些值，请为路径变量提供完全解析的绝对路径。OPENCLAW_WORKSPACE_DIR 也不会展开前导 ~，因为它直接传给 path.resolve。OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 会展开 ~。工作区本地 .env 文件会丢弃整个 OPENCLAW_* 命名空间，因为它是不可信输入。请在受信任的全局 .env 中设置这些变量，位于 $OPENCLAW_STATE_DIR/.env，默认情况下为 ~/.openclaw/.env。

Docker Compose 遵循其自身的 插值规则。在捆绑的 docker-compose.yml 中，来自项目 .env 的 OPENCLAW_WORKSPACE_DIR 会选择工作区绑定挂载的主机目录。容器侧的 OPENCLAW_WORKSPACE_DIR 保持固定为 /home/node/.openclaw/workspace。

Secret 引用与 ${ENV} 字符串¶

OpenClaw 支持两种由环境变量驱动的模式：

• 配置值中的 ${VAR} 字符串替换。
• 用于支持 secrets 引用的字段的 SecretRef 对象（{ source: "env", provider: "default", id: "VAR" }）。

两者都会在激活时从进程环境中解析。SecretRef 详情记录在 密钥管理 中。 配置 env 块本身不会解析 SecretRef 或 file:... 简写值。

路径相关环境变量¶

| 变量 | 用途 |

Agent 辅助工具下载¶

设置 OPENCLAW_OFFLINE=1 可阻止 OpenClaw 下载其固定版本的 fd 和 ripgrep 辅助二进制文件。OpenClaw tools 目录下已有的辅助工具以及可用的系统二进制文件仍然可用。缺失的辅助工具会保持不可用，而不会触发网络请求。

日志¶

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_* 前缀会被静默忽略。受支持的 provider 和文件系统观察变量保留其 文档中记载的名称。

如果启动时 Gateway 进程上仍设置了其中任何变量，OpenClaw 会发出单个 Node 弃用警告（OPENCLAW_LEGACY_ENV_VARS），列出检测到的前缀和总数。通过将旧前缀替换为 OPENCLAW_ 来重命名每个值（例如将 CLAWDBOT_GATEWAY_TOKEN 改为 OPENCLAW_GATEWAY_TOKEN）。旧名称不生效。

相关¶

• Gateway 配置
• FAQ：环境变量和 .env 加载
• 模型概览