OpenClaw跨平台环境变量配置：Windows/macOS/Linux避坑指南-开发者社区

部署OpenClaw（原Clawdbot）这种本地智能体框架，很多人以为最难的是把代码拉下来跑通，其实真正卡人的往往是环境变量。我前段时间给一台新机器部署这套东西，依赖装好、服务代码也确认没有改动，运行时报错却直接落在OPENCLAW_API_KEY is not set。翻遍本地配置文件，密钥确实在文件里，后来才发现不同操作系统对这个变量的生效时机和读取范围差异很大，并不是“填进去就行”这么简单。

这篇内容就把我在 Windows、macOS、Linux 三种环境下给 OpenClaw 配置环境变量的具体方法、踩过的坑、以及最终沉淀下来的排查套路完整写出来。如果你正在为某个本地智能体项目折腾环境变量，不管是新手还是已经部署过几次的开发者，这里应该都有你用得上的细节。

1. 部署前先搞明白：环境变量在 OpenClaw 里到底扮演什么角色

1.1 一套本地智能体服务的真实启动路径

OpenClaw 从原 Clawdbot 演进到现在，核心定位已经变成一个可以本地运行的智能体框架，简单说就是你在自己的机器上跑一个程序，让它能调用各种模型接口、读写文件、执行指令，最后通过终端交互替你完成任务。

这类程序启动的时候，通常不会一上来就把所有配置读一遍，而是遵循一套固定顺序：先看环境变量里有没有需要的键值，没有就去找项目目录下的 .env 文件，再找不到就读取本地配置文件，最后才轮到内置默认值。这个顺序决定了环境变量是优先级最高的一层配置入口，也解释了为什么很多参数明明写在文件里，程序却依然报错说没设置。

举个例子，我在一台机器上同时跑过 OpenClaw 的两个实例，一个用于日常实验，一个用于定时任务。两者的模型接口地址、日志级别完全不同。如果我把配置写在代码里，每次切换都要改文件，而且容易误提交。用环境变量之后，只需在启动前切一下变量值，同一个代码目录就能跑出完全不同的行为。

1.2 需要优先配好的几个变量

根据我实际操作的经验，OpenClaw 本地部署时最常涉及以下几类环境变量。我按重要程度排了个顺序，方便你对照检查：

变量名	作用说明	示例值
OPENCLAW_API_KEY	模型服务商的访问密钥，缺少它程序会直接启动失败	一串敏感字符串
OPENCLAW_MODEL_ENDPOINT	模型接口地址，本地模型和在线服务地址不同	http://127.0.0.1:8000/v1
OPENCLAW_MODEL_NAME	指定默认使用的模型名称	可以是任意模型标识
OPENCLAW_LOG_LEVEL	日志输出级别，调试阶段建议设为 debug	debug / info / warning
OPENCLAW_WORKSPACE	工作目录路径，所有生成文件都会放这里	/data/openclaw/workspace

这几项里，前三项决定程序能不能跑起来，后两项决定跑起来之后好不好排查、文件放哪里。建议在动手配置前先在纸上列一份自己的变量清单，把密钥、目录、端口这些信息整理好，后面操作会流畅很多。

1.3 为什么没必要把所有配置都塞进代码

很多新手习惯把配置直接写在代码里，图省事。但本地部署一旦涉及多个环境，硬编码的缺点会非常明显。密钥混在代码文件里，只要代码目录被同步备份，密钥就跟着一起泄露。另外配置文件一旦被程序读取后锁定，改动必须重启进程，没办法做到运行中临时调整。

环境变量的优势在于它独立于代码存在。你可以把敏感信息放在系统层面，代码仓库里只保留读取变量的逻辑。哪怕代码被别人拿去看，也看不到真实密钥。这一点在多人协作、代码交给别人复现的时候尤其重要。我自己的习惯是：代码里只出现变量的读取，真实值永远只在部署机器的环境变量或加密配置里出现。

2. Windows 环境下设置环境变量的完整操作

2.1 图形界面方式与命令行方式怎么选

Windows 是很多本地部署用户最开始接触的系统，它的环境变量设置入口藏得比较深，但胜在图形界面直观。右键“此电脑”，选“属性”，进入“高级系统设置”，再点“环境变量”，就能看到用户变量和系统变量两个列表。

这里我先说结论：如果只是给当前用户跑 OpenClaw，用户变量足够，系统变量反而容易污染整台机器。系统变量修改后所有用户和所有进程都会读到，一旦变量名冲突，排查时非常痛苦。我见过有人把模型密钥写成系统变量，后来其他项目读取同名变量时拿到了错误的值，查了整整一晚上才发现是被系统变量覆盖了。

图形界面方式适合一次性添加或修改少量变量，比如刚装完程序，需要补一两个密钥。如果是频繁调整、多台机器重复操作，命令行方式效率高得多。

2.2 PowerShell 的两种写入方式：临时与持久

Windows 上推荐用 PowerShell 而不是旧版 cmd，因为 PowerShell 对环境变量的操作方法更完整。

临时变量只在当前终端窗口有效，终端一关就消失，适合测试时快速验证某个配置是否正确，或者临时切换日志级别：

$env:OPENCLAW_LOG_LEVEL = 'debug'

设置完可以用同一个终端启动 OpenClaw，程序里读取到的就是刚才写入的值。这种方式的优点是不会污染系统，缺点是无法跨终端使用。如果你开了新的终端窗口，变量就没了，很容易误以为配置没生效。

持久化变量才是部署时真正会用到的。PowerShell 里正确写法是这样：

[Environment]::SetEnvironmentVariable('OPENCLAW_API_KEY', '你的密钥', 'User')

注意第三个参数，'User' 表示当前用户的持久化变量，'Machine' 表示系统级变量，'Process' 才是当前进程临时变量。我建议一律使用 'User'，避免不必要的系统级污染。

写入持久化变量之后，当前终端并不会立刻读取到新值。这是新手最容易疑惑的地方。必须重新打开一个终端窗口，或者用下面的命令手动刷新：

$env:OPENCLAW_API_KEY = [Environment]::GetEnvironmentVariable('OPENCLAW_API_KEY', 'User')

配置完之后，验证一下是否生效。PowerShell 里查看当前值：

Get-ChildItem Env:OPENCLAW_API_KEY

或者只看单个变量：

$env:OPENCLAW_API_KEY

输出结果能看到真实值，就说明配置写入成功。

2.3 我实操中遇到的 Windows 专属问题

第一个坑是旧版 setx 命令。很多老教程推荐用 setx 设置环境变量，它在 cmd 里确实能用，但这是 Windows 7 时代的老工具，有几个明显问题：写入时值不能过长，超过 1024 字符会被截断；它写的是注册表里的持久值，当前终端立即不更新；某些字符处理有问题，值里带空格或引号时容易出错。所以我现在的做法是彻底避开 setx，统一用上文的 .NET 方法。

第二个坑是变量值里的路径分隔符。Windows 路径默认用反斜杠，比如 C:\Users\你的用户名\openclaw，而反斜杠在某些环境变量解析里会被当作转义字符。虽然 Windows 环境变量本身对反斜杠没有特殊处理，但 OpenClaw 如果底层用了解析逻辑，容易把路径弄乱。稳妥的办法是在变量值里改用正斜杠 C:/Users/你的用户名/openclaw，大多数现代程序都能正常识别。

第三个坑跟 Git Bash 和 WSL 有关。很多人在 Windows 上安装 Git 之后习惯用 Git Bash 操作，但 Git Bash 里设置环境变量的语法和 PowerShell 完全不同，用 export 写入的变量只在当前 Bash 会话有效，Windows 图形界面和 PowerShell 都读不到。同理，WSL 里的环境变量和 Windows 原生环境变量是两套体系。如果你在 WSL 里运行 OpenClaw，就得在 WSL 内部按 Linux 的方式配置，而不是在 Windows 系统变量里设置。

3. macOS 环境下设置环境变量的正确打开方式

3.1 先把 zsh 的配置文件梳理清楚

macOS 从 Catalina 之后默认 shell 是 zsh，配置环境变量主要落在三个文件，很多人第一次接触会分不清该写哪个。

~/.zshrc是每次打开终端都会读取的配置，适合放日常使用的变量和别名。~/.zprofile是登录 shell 时读取一次，主要面向登录阶段需要初始化的东西。~/.bash_profile则是给 bash 用的，macOS 默认不用它，除非你手动切换了 shell。

我的建议是，OpenClaw 这类本地服务的环境变量一律写进~/.zshrc。原因很简单：你从终端启动 OpenClaw，打开终端就会加载 .zshrc，变量自然就生效了。写入 .zprofile 虽然也能用，但某些终端环境下不会触发登录 shell 加载逻辑，表现不稳定。

如果你在旧版本 macOS 上还在用 bash 作为默认 shell，那就要写~/.bash_profile或者~/.bashrc。具体区分方式很简单：终端里执行echo $SHELL，输出 /bin/zsh 就操作 zsh 的文件，输出 /bin/bash 就操作 bash 的文件。

3.2 配置 OpenClaw 变量的具体写法和刷新办法

先打开终端，编辑~/.zshrc。如果你不熟悉命令行编辑器，可以用 cat 追加的方式快速写入：

echo 'export OPENCLAW_API_KEY="你的密钥"' >> ~/.zshrc echo 'export OPENCLAW_MODEL_ENDPOINT="http://127.0.0.1:8000/v1"' >> ~/.zshrc

这里有两处细节值得注意。第一，export 后面的值要用双引号包裹，如果值里面本身包含空格或特殊字符，不包引号会导致被拆成多个词，程序读取时只能拿到第一段。第二，用两个空格双引号的方式虽然方便，但如果同一个文件执行了多次，会出现重复行，虽然不影响功能，但看着很乱。我更推荐用echo 'export OPENCLAW_API_KEY=xxxx' >> ~/.zshrc之后，再用code ~/.zshrc打开文件，手动清理和补充其余变量。

写入之后必须刷新加载，否则当前终端读不到新变量：

source ~/.zshrc

source 的本质是让当前 shell 重新执行一遍配置文件，把新加的行加载到内存里。之后用env | grep OPENCLAW或者直接echo $OPENCLAW_API_KEY验证是否生效。如果输出的是密钥内容，说明配置成功。

3.3 从 Dock 启动时变量丢失的解决办法

macOS 有一个让很多部署者头疼的问题：你在终端里配置好了环境变量，从终端启动 OpenClaw 一切正常，但双击程序图标或者从 Dock 启动时，程序反而读不到这些变量。

原因在于 macOS 的图形界面应用不是从终端继承环境变量的，它们是直接由 launchd 启动的服务。你在 .zshrc 里设置的变量，只对终端及终端派生的进程生效，图形程序根本走不到这一层。

解决思路有两种。如果你需要临时验证，可以在终端里执行下面的命令，把变量注入到图形应用可以读取的系统层面：

launchctl setenv OPENCLAW_API_KEY 你的密钥

这个命令不需要 export，等号换成了空格。执行后变量会立即对新的图形应用生效。缺点是重启后丢失，需要重新设置，适合应急，不适合长期部署。

长期方案是写一个 LaunchAgent 配置，放在~/Library/LaunchAgents/目录下，让 macOS 在登录时自动设置变量。配置文件基本长这样：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.local.openclaw.env</string> <key>ProgramArguments</key> <array> <string>/bin/launchctl</string> <string>setenv</string> <string>OPENCLAW_API_KEY</string> <string>你的密钥</string> </array> <key>RunAtLoad</key> <true/> </dict> </plist>

保存后运行launchctl load ~/Library/LaunchAgents/com.local.openclaw.env.plist加载。这样每次登录都会自动注入变量，适用面比手动命令稳得多。

3.4 我推荐在 macOS 上配置变量的小技巧

环境变量写在全局配置文件里，时间久了会积累大量不用的变量，每次 source 之前都担心污染。我个人的做法是结合 direnv 工具，在 OpenClaw 的项目目录下建一个.envrc文件，进入目录自动加载，离开目录自动卸载。

安装 direnv 之后，在项目目录里编辑.envrc：

export OPENCLAW_API_KEY="你的密钥" export OPENCLAW_MODEL_ENDPOINT="http://127.0.0.1:8000/v1"

然后执行direnv allow激活。这样变量只对当前目录的项目生效，其他项目完全不受影响。多项目并行部署时尤其好用。

4. Linux 环境下设置环境变量的三条路径

4.1 .bashrc 和 systemd 之间的断层

Linux 上最常见的误区是改~/.bashrc。对普通终端启动的程序，这个方案没问题，但 OpenClaw 如果配置成开机自启的服务，情况就完全不同了。

systemd 是 Linux 主流的服务管理器，它启动进程时不会加载/etc/profile、~/.bashrc、~/.zshrc这些 shell 配置文件。系统服务直接由 PID 1 启动，环境变量只能依赖 systemd 自己的配置来源。换句话说，你在 .bashrc 里写的 export 对 systemd 来说完全不存在，服务启动后就会报环境变量缺失。

所以关键是区分两套场景：手动在终端启动，走 shell 配置；设置成服务自动启动，走 systemd 配置。如果你打算让 OpenClaw 作为常驻服务跑，直接抛弃 .bashrc 的方案，从一开始就用 systemd 来管理变量。

4.2 给 OpenClaw 写一个带 EnvironmentFile 的 systemd 服务

systemd 提供两种注入变量的方式：Environment 和 EnvironmentFile。Environment 适合写少量简单变量，直接写在 unit 文件里。EnvironmentFile 适合变量较多的情况，把变量集中放在一个文件里，管理起来更清晰。

我给 OpenClaw 写服务配置时会优先选 EnvironmentFile。先创建一个变量文件，放在/etc/openclaw/openclaw.env：

OPENCLAW_API_KEY=你的密钥 OPENCLAW_MODEL_ENDPOINT=http://127.0.0.1:8000/v1 OPENCLAW_LOG_LEVEL=info

注意这个文件里的变量定义不要带export前缀，也不要给值加引号，除非值本身就包含空格。和 shell 语法有细微差别，很多人第一次写会顺手带上 export，结果 systemd 把整行当作变量名解析，自然失败。

然后创建服务文件/etc/systemd/system/openclaw.service：

[Unit] Description=OpenClaw Service [Service] User=你的用户名 EnvironmentFile=/etc/openclaw/openclaw.env ExecStart=/opt/openclaw/launch Restart=on-failure [Install] WantedBy=multi-user.target

执行下面的命令让配置生效：

sudo systemctl daemon-reload sudo systemctl start openclaw sudo systemctl enable openclaw

启动后如果发现服务异常，先执行systemctl status openclaw，再执行journalctl -u openclaw -f看日志。如果想用systemctl show openclaw查看 systemd 实际加载到的变量值，重点确认 Environment 行是否包含你设置的内容。

这里有一个容易忽略的点：如果 OpenClaw 内部还会调用其他的子进程，而这些子进程依赖某种运行时变量，比如代理设置，那么你也得把它们写进 EnvironmentFile。因为 systemd 启动的进程只继承 unit 文件里明确指定的环境，不会自动读取系统中的/etc/profile.d/内容。

4.3 容器部署时如何把变量安全传进去

如果你采用的是容器化部署方式，环境变量配置逻辑又不一样。容器和宿主机之间是隔离的，宿主机环境变量不会自动进入容器，程序里的密钥必须显式传入。

最基础的做法是在启动命令里加-e参数：

docker run -e OPENCLAW_API_KEY=你的密钥 -e OPENCLAW_LOG_LEVEL=debug --name openclaw openclaw-image

这样写适合启动前临时测试。如果变量比较多，更推荐用--env-file：

docker run --env-file ./openclaw.env --name openclaw openclaw-image

--env-file会读取整个文件中的变量，一次性注入容器。文件格式和 systemd 的 EnvironmentFile 几乎一样，一行一个键值对。注意这个文件不要提交到代码仓库，否则密钥等于跟着代码走了一趟，毫无安全意义。

如果用的是 docker-compose，则在 compose 文件里添加：

services: openclaw: image: openclaw-image env_file: - ./openclaw.env

或者在 environment 字段下明确列出变量。两者可以混用，但如果同一个变量在两个位置都出现，environment 字段的值优先，覆盖 env_file 的值。这个优先级关系在实际排错中很有用。

在 Linux 上，我更推荐通过环境变量而不是把密钥写进容器镜像。镜像一旦构建出来，里面的环境变量被固化在镜像分层里，任何能够访问镜像的人都能提取，这是一个比较隐蔽的信息暴露渠道，应用运行时注入才更干净。

5. 我的排错清单与一套跨平台变量管理套路

5.1 变量明明配置了却不生效，问题大多出在这几处

这类问题我遇到太多次了，总结下来就几个高频原因。第一，终端缓存了旧环境。写入变量后没重新打开终端或者没 source，程序读到的还是启动终端时的老环境。第二，变量写到了错误的作用域。Windows 上写了用户级变量但程序以系统进程方式启动，macOS 上写了 shell 变量但程序从 Dock 启动，Linux 上写了 .bashrc 但服务由 systemd 托管。第三，变量末尾带了隐藏在值里的字符，比如换行符，肉眼根本看不到。

这里给出一份我的排错顺序表，照着走能快速定位问题：

排查步骤	操作命令	判断标准
确认变量是否真实存在	Windows:`$env:OPENCLAW_API_KEY` macOS/Linux:`echo $OPENCLAW_API_KEY`	有输出就说明存在
确认变量是否跨进程可见	重启终端后再执行一次上面的命令	仍然有输出才合格
确认变量是否被空格或引号影响	用`echo ${#OPENCLAW_API_KEY}`查看长度	长度和预期一致
确认服务进程加载了同一套配置	用`systemctl show openclaw`或容器 exec 进入进程查看	实际环境和配置环境一致

我自己遇到最多的案例是最后一种，配置文件没问题、环境变量也存在，但程序就是读不到。最后发现 OpenClaw 内部是通过配置文件加载变量的，并且配置文件的优先级高于环境变量，里面写了一个空的密钥覆盖了环境变量里的值。这提醒我，排查环境变量问题之前，先确认程序自己配置了哪些读取来源，不要想当然认为环境变量一定有效。

5.2 敏感信息别直接躺进 shell 历史

配置环境变量时最容易忽略的安全细节是历史命令记录。你在终端里执行export OPENCLAW_API_KEY="你的密钥"，这行命令会被 shell 记录到历史文件。比如 zsh 写入~/.zsh_history，bash 写入~/.bash_history。如果这台机器之后被登录或者文件被同步，密钥等于直接暴露了。

更稳妥的做法是：不要在命令行里直接写真实密钥，先用read -s交互式输入，再导出到变量：

read -s OPENCLAW_API_KEY export OPENCLAW_API_KEY

这样终端历史里不会留下密钥内容。或者把变量写进 .env 文件，然后通过加载工具读取。比如在项目根目录用 Python 提供的加载机制，或者用 direnv 之类的工具自带读取逻辑，都不需要把密钥写进命令行。

另外建议顺手做两件事：给历史文件加权限限制，chmod 600 ~/.bash_history ~/.zsh_history；定期检查history命令输出，发现敏感命令就直接清空history -c。虽然不是百分百防止泄露，但至少能把常见暴露路径堵住一半。

另外，密钥这东西建议定期更换。很多人本地部署之后同一个密钥用一年，一旦有次日志打印了完整变量，密钥基本就废了。我习惯在项目的配置模板里写注释，标注“当前密钥最后修改日期”，换密钥时能快速提醒自己更新。

5.3 用统一的 .env 模板管理多平台变量

跨平台部署次数多了之后，我建议尽量把变量内容统一管理。具体做法是：在项目仓库里保存一个.env.example模板，里面只写变量名和占位符，真实值永远放在本机的.env文件或者系统环境变量里。

模板内容大致这样：

# OpenClaw 配置模板 OPENCLAW_API_KEY=change_me OPENCLAW_MODEL_ENDPOINT=http://127.0.0.1:8000/v1 OPENCLAW_MODEL_NAME=local_model OPENCLAW_LOG_LEVEL=debug OPENCLAW_WORKSPACE=./data

模板提交到仓库，真实.env加入.gitignore。换新机器部署时，复制模板、填入真实值、导入到对应系统。Windows 上可以把.env文件的键值用脚本导入注册表；macOS 和 Linux 上可以写一个小脚本逐行读取并 export。这么做的好处是变量名在各平台完全一致，程序侧永远用同一套读取逻辑，不用为每个平台维护不同的配置格式。

如果你同时维护多台机器，还可以把这个导入脚本放在配置仓库里，每台机器执行一次就完成环境同步。脚本尽量简单，比如 Linux 下这样写：