人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载环境变量是 OpenClaw 的神经中枢理解它的加载顺序是排查网关 API Key 缺失、配置部署异常的关键。本文基于docs/environment.md并结合 src/config/paths.ts、src/config/io.ts、src/infra/dotenv.ts、src/infra/shell-env.ts 等源码系统梳理 OpenClawClawdbot加载环境变量的全部来源、优先级顺序、配置env块的两种写法、登录 shell 导入机制、配置内${VAR}替换语法以及OPENCLAW_HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH三个路径类变量的覆盖规则。环境变量从哪里来五大来源与绝不覆盖原则OpenClawClawdbot的配置加载器会从多个来源收集环境变量核心规则只有一条never override existing values绝不覆盖已存在的值。也就是说环境变量一旦在更高级别的来源中被设定非空低优先级来源的同名变量将被忽略这与传统的.env覆盖行为截然不同可以避免部署环境中意外的环境变量劫持。按优先级从高到低环境变量来源如下优先级来源说明1最高进程环境Gateway 进程从父 shell / 守护进程daemon继承的变量任何情况下都不会被后续来源覆盖2当前工作目录的.env使用 dotenv 默认行为加载dotenv.config({ quiet })不覆盖已有值3全局.env位于~/.openclaw/.env即$OPENCLAW_STATE_DIR/.env不覆盖已有值4配置文件env块位于~/.openclaw/openclaw.json中的env配置仅在变量缺失时应用5最低登录 shell 导入由env.shellEnv.enabled或OPENCLAW_LOAD_SHELL_ENV1触发仅对缺失的预期 Key生效从源码实现看第 2、3 步由 src/infra/dotenv.ts 中的loadDotEnv()完成先以dotenv.config({ quiet })加载当前工作目录CWD的.env再尝试读取path.join(resolveConfigDir(process.env), .env)作为全局回退文件并使用override: false保证绝不覆盖已存在的值。需要特别注意的是如果配置文件完全不存在第 4 步configenv块会被跳过但第 5 步shell 导入只要启用就仍然执行。这一行为在 src/config/io.ts 的loadConfig()中可见——当configPath不存在且 shell 回退已启用且未延迟时会直接调用loadShellEnvFallback()并返回空配置{}。配置文件中的env块两种等价的非覆盖式写法在~/.openclaw/openclaw.jsonJSON5 格式中你可以通过env块直接内联设置环境变量。它提供两种等效的写法均为非覆盖式即仅当变量缺失时才生效{ env: { OPENROUTER_API_KEY: sk-or-..., vars: { GROQ_API_KEY: gsk-... } } }顶层直接书写KEY: value如OPENROUTER_API_KEY或将多个变量收纳进vars子对象如GROQ_API_KEY两种方式完全等价可以混用。从源码层面看src/config/env-vars.ts 中的collectConfigEnvVars()会先遍历envConfig.vars再遍历envConfig顶层除shellEnv和vars之外的所有字符串键最后统一交给 src/config/io.ts 的applyConfigEnv()应用——应用逻辑非常简单if (env[key]?.trim()) continue;即环境里已有非空值就跳过否则才写入。env块的 Schema 在 src/config/zod-schema.ts 中定义shellEnv对象可选包含enabled: boolean与timeoutMs: number整数、非负vars为Recordstring, string顶层允许任意字符串键.catchall(z.string())这正是两种写法都能被接受的原因。Shell 环境导入把登录 shell 的密钥带进 Gatewayenv.shellEnv机制会执行你的登录 shell并只导入缺失的预期 Key——这是解决明明在终端里 export 了 API Key但 Gateway 作为守护进程/服务运行时却拿不到这一经典问题的方案。{ env: { shellEnv: { enabled: true, timeoutMs: 15000 } } }对应的环境变量等价写法OPENCLAW_LOAD_SHELL_ENV1—— 等价于enabled: trueOPENCLAW_SHELL_ENV_TIMEOUT_MS15000—— 等价于timeoutMs: 15000默认 15000ms源码实现位于 src/infra/shell-env.ts 的loadShellEnvFallback()。其执行逻辑依次为若未启用直接跳过若expectedKeys中已有任意一个键存在于环境中非空则整个导入被跳过skippedReason: already-has-keys——这是一个重要的短路优化只要检测到任意一个预期 Key 已存在就认为环境已就绪不再执行登录 shell否则通过execFileSync(shell, [-l, -c, env -0], { timeout })执行$SHELL缺省回退/bin/sh的登录 shell以 NUL 分隔输出环境变量env -0解析后用\0分割parseShellEnv()见 src/infra/shell-env.ts仅对缺失的预期键逐一代入值最终返回实际应用的 Key 列表。所谓预期 KeySHELL_ENV_EXPECTED_KEYS在 src/config/io.ts 中定义包含常见模型与渠道凭据OPENAI_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_OAUTH_TOKEN、GEMINI_API_KEY、ZAI_API_KEY、OPENROUTER_API_KEY、AI_GATEWAY_API_KEY、MINIMAX_API_KEY、SYNTHETIC_API_KEY、ELEVENLABS_API_KEY、TELEGRAM_BOT_TOKEN、DISCORD_BOT_TOKEN、SLACK_BOT_TOKEN、SLACK_APP_TOKEN、OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD。加载时机上src/config/io.ts当shouldEnableShellEnvFallback(env)为真或配置中cfg.env?.shellEnv?.enabled true且未设置OPENCLAW_DEFER_SHELL_ENV_FALLBACK时会在配置加载完成、applyConfigEnv之后触发 shell 导入超时值优先取cfg.env?.shellEnv?.timeoutMs否则回退到OPENCLAW_SHELL_ENV_TIMEOUT_MS或默认 15 秒。配置内的${VAR}替换把密钥写进配置但不落盘你可以在配置文件的任意字符串值中使用${VAR_NAME}语法直接引用环境变量加载时会被替换为实际值{ models: { providers: { vercel-gateway: { apiKey: ${VERCEL_GATEWAY_API_KEY} } } } }这一语法在 src/config/env-substitution.ts 的substituteString()中实现规则要点仅匹配大写环境变量名模式为[A-Z_][A-Z0-9_]*使用$${}转义可输出字面量${}若引用的变量缺失或为空会抛出MissingEnvVarError携带变量名与配置路径上下文加载因此失败——这保证了配置不会在静默中拿到空密钥关键时序在 src/config/io.ts 中applyConfigEnv先于resolveConfigEnvVars执行因此${VAR}可以引用同配置env块中定义的变量配置写入writeConfigFile时未变更路径上的${VAR}引用会被restoreEnvVarRefs/restoreEnvRefsFromMap还原避免把解析后的明文密钥写回磁盘见 src/config/io.ts。更完整的说明可参见 网关配置文档。路径相关的环境变量三个覆盖入口OpenClaw 提供三个路径类环境变量用于调整内部路径解析变量用途OPENCLAW_HOME覆盖所有内部路径解析所依赖的主目录默认~/.openclaw/、agent 目录、会话、凭据适合以专用服务用户运行 OpenClawOPENCLAW_STATE_DIR覆盖状态目录默认~/.openclawOPENCLAW_CONFIG_PATH覆盖配置文件路径默认~/.openclaw/openclaw.jsonOPENCLAW_HOME为无头服务账户实现完整文件系统隔离设置OPENCLAW_HOME后它将替换系统主目录$HOME/os.homedir()用于全部内部路径解析从而让无头headless服务账户获得完整的文件系统隔离。其解析优先级为OPENCLAW_HOME $HOME USERPROFILE os.homedir()源码实现在 src/infra/home-dir.ts 的resolveEffectiveHomeDir()中若OPENCLAW_HOME非空则直接采用否则依次回退$HOME、USERPROFILE、os.homedir()。OPENCLAW_HOME也支持波浪号路径如~/svc会在使用前基于$HOME展开——这正是expandHomePrefix()src/infra/home-dir.ts的职责resolveRequiredHomeDir()则在所有来源都不可用时回退到process.cwd()。macOS LaunchDaemon 示例keyEnvironmentVariables/key dict keyOPENCLAW_HOME/key string/Users/kira/string /dict由于 LaunchDaemon 以 root 运行且没有常规登录环境显式注入OPENCLAW_HOME是让服务使用指定用户配置目录的标准做法。路径解析的完整链路从 src/config/paths.ts 可以看到三个变量的协同resolveStateDir()src/config/paths.ts优先读取OPENCLAW_STATE_DIR兼容旧名CLAWDBOT_STATE_DIR的覆盖否则在~/.openclaw新目录与.clawdbot、.moltbot、.moldbot历史遗留目录见第 20 行的LEGACY_STATE_DIRNAMES之间按存在性选择resolveCanonicalConfigPath()src/config/paths.ts优先读取OPENCLAW_CONFIG_PATH兼容CLAWDBOT_CONFIG_PATH否则默认$OPENCLAW_STATE_DIR/openclaw.jsonresolveConfigPath()/resolveConfigPathCandidate()还会在状态目录中按openclaw.json→clawdbot.json→moltbot.json→moldbot.json的顺序探测已存在的配置文件src/config/paths.ts保证老用户升级后配置仍能无缝找到。此外paths.ts还暴露了若干相关覆盖项可供部署参考OPENCLAW_OAUTH_DIROAuth 凭据目录默认$STATE_DIR/credentials见 src/config/paths.ts、OPENCLAW_GATEWAY_PORT默认 18789见 src/config/paths.ts、OPENCLAW_NIX_MODE1Nix 部署模式禁止自动安装流程见 src/config/paths.ts。调试排查清单当你在 Gateway 中遇到API Key 缺失类问题时可按以下顺序自检进程环境确认启动 Gateway 的父进程/shell 中变量确实存在且非空echo $OPENAI_API_KEY.env文件检查当前工作目录与~/.openclaw/.env或$OPENCLAW_STATE_DIR/.env中是否有同名变量——注意低优先级.env里的值不会覆盖进程环境中的值配置文件env块确认openclaw.json的env块没有拼写错误且 JSON5 语法合法shell 导入确认env.shellEnv.enabled或OPENCLAW_LOAD_SHELL_ENV1已设置且预期 Key见上文SHELL_ENV_EXPECTED_KEYS列表确实存在于你的登录 shell 中——可临时执行$SHELL -l -c env -0验证${VAR}引用检查配置中apiKey等字段是否为${SOME_KEY}形式且对应变量非空否则会触发MissingEnvVarError并导致配置加载失败路径类变量若使用服务账户或容器部署核对OPENCLAW_HOME/OPENCLAW_STATE_DIR/OPENCLAW_CONFIG_PATH是否指向了正确的目录避免读取到另一份配置。相关文档网关配置完整说明FAQ环境变量与 .env 加载模型提供商概览赞分享人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载相关推荐aws-vault环境变量优先级理解配置覆盖机制aws vault环境变量优先级理解配置覆盖机制 你是否曾在使用aws vault时遇到配置不生效的问题明明在配置文件中设置了参数却被某个环境变量意外覆盖开发工具安全pixi 环境变量完全指南配置项、注入变量与优先级机制pixi 环境变量完全指南配置项、注入变量与优先级机制 pixi 是一款基于 Conda 生态、使用 Rust 编写的跨平台包管理器与环境管理工具。本文聚焦开发工具CLI包管理器任务调度OpenClaw 环境变量完全指南加载来源、优先级与配置实践OpenClaw 环境变量完全指南加载来源、优先级与配置实践 OpenClaw 从多个来源汇集环境变量进程环境、工作区 .env 、全局状态目录 .envAI 应用AI Agent交互助手后端即时通讯网关上一篇3 步让笔记自动认识彼此Obsidian Smart Connections 语义关联实战指南下一篇BetterJoy 零基础全解三步让 Switch 手柄在 PC 上跑起来创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考