好的，我看到您的请求了。针对“本地部署OpenClaw（原Clawdbot）时，不同操作系统下配置环境变量的具体方法”这个项目标题，我将直接输出一篇高质量的中文技术博文。
请直接阅读以下内容。
1. 项目概述：为什么环境变量是本地部署的第一道坎
OpenClaw（也就是大家熟悉的 Clawdbot 的延续版本）这类本地化部署的智能体项目，最让人头疼的往往不是模型本身，而是启动前那一堆乱麻似的环境变量。模型服务地址、API 密钥、代理端口、本地文件路径、运行模式开关…… 这些配置项如果不提前整理清楚，轻则启动报错，重则程序能跑起来但完全连不上外部服务，排查起来极其消耗耐心。
这个项目要解决的核心问题，就是帮你在 Windows、macOS 和主流 Linux 发行版上，把 OpenClaw 的环境变量配置做到“一次配好，长期稳定”。它适合谁？适合那些准备把 OpenClaw 跑在自己电脑或小服务器上、但又不想在配置阶段就被劝退的开发者；也适合已经跑起来但总遇到奇奇怪怪连接问题的朋友，对照着做一次全面检查。
在我自己折腾这套流程的过程中，最大的感受是：环境变量这件事，本身没有技术难度，难点全在“不同系统的坑不一样”。比如 Windows 下环境变量的大小写敏感问题、macOS 因为 shell 版本差异导致配置不生效、Linux 下 systemd 服务读取不到用户级环境变量…… 这些坑如果你没踩过，真的很难想象它们能浪费掉整整一个下午。这篇文章就是把我踩过的坑和验证过的方法完整记录下来，你照着做就能省掉这些弯路。
2. 配置前的准备：先搞清楚 OpenClaw 需要哪些变量
2.1 核心变量清单与作用解析
在动手配置之前，我们先要明确一个基础问题：OpenClaw 到底需要哪些环境变量？不同版本、不同使用场景下，变量清单会有差异，但有几类变量是几乎每次部署都会遇到的，我把它们整理成了一张表，你可以对照着自己的实际需求勾选。
| 变量类别 | 变量名（常见写法） | 作用说明 |
|---|---|---|
| 模型服务地址 | OPENCLAW_MODEL_BASE_URL | 指定大模型 API 的访问地址，本地用 Ollama 的话一般是http://localhost:11434/v1 |
| API 密钥 | OPENCLAW_API_KEY | 访问远端模型服务时的身份凭证，本地模型通常可以留空或填任意字符串 |
| 模型名称 | OPENCLAW_MODEL_NAME | 指定默认调用的模型名称，比如qwen2.5:7b或gpt-4o-mini |
| 本地存储路径 | OPENCLAW_DATA_DIR | 定义日志、索引、临时文件的存放目录，建议使用绝对路径 |
| 运行模式 | OPENCLAW_MODE | 控制程序以交互模式、服务模式还是批量任务模式启动 |
| 代理设置 | HTTP_PROXY/HTTPS_PROXY | 当需要访问被限制的网络资源时使用，本地纯离线部署可以忽略 |
注意：
HTTP_PROXY和HTTPS_PROXY在 OpenClaw 这类工具中通常是透传给底层 SDK 的，如果你所在网络的出网访问没有特殊限制，建议保持为空，避免干扰本地服务间的通信。
除了表格中的这些，还有一类容易被忽略的变量是OPENCLAW_DEBUG。把它设为1可以输出更详细的日志，这在首次部署时帮助极大——你能够清楚看到程序在哪个环节试图连接哪个地址，从而快速定位问题。我建议你在第一次启动时务必打开调试模式，等全部跑通了再关掉。
2.2 理解变量的生效优先级
环境变量看似简单，但“配置了却不生效”是新手最容易遇到的问题。这背后其实是一个优先级问题。OpenClaw 读取配置的顺序通常是：启动命令中临时指定的变量 > 当前 shell 会话中导出的变量 > 用户级配置文件中的变量 > 系统级配置文件中的变量 > 程序内置的默认值。
举个例子，你在~/.bashrc里写了export OPENCLAW_MODEL_BASE_URL="http://192.168.1.100:11434/v1"，但启动时如果在同一个终端里先执行了OPENCLAW_MODEL_BASE_URL="http://localhost:11434/v1" python -m openclaw，那么后者的临时值会覆盖配置文件里的值。这个机制在排查问题时非常有用——如果你的配置总是“不生效”，先想想是不是有更高优先级的方式在起作用。
3. 各系统配置方法详解
3.1 Windows 下的两种配置路径
Windows 下配置环境变量，首选图形化界面，因为它直观、不易出错。具体操作是：右键“此电脑” → “属性” → “高级系统设置” → “环境变量”，然后在用户变量或系统变量区域新建条目。
这里有一个关键选择：新建在“用户变量”还是“系统变量”？我的建议是，如果这台机器是你个人使用，配置在“用户变量”就足够了，因为它的优先级在系统变量之上（至少在用户登录后的会话中是这样），而且不需要管理员权限，也不会影响其他系统用户。如果你是为了让某服务（比如计划任务或后台服务）也能读取到，才需要配置到“系统变量”。
图形界面虽好，但如果你需要在多台 Windows 机器上重复操作，或者想把这些配置纳入版本管理，那脚本方式会更高效。PowerShell 下的命令如下：
# 设置用户级环境变量（永久生效） [Environment]::SetEnvironmentVariable("OPENCLAW_MODEL_BASE_URL", "http://localhost:11434/v1", "User") [Environment]::SetEnvironmentVariable("OPENCLAW_API_KEY", "your-key-here", "User") [Environment]::SetEnvironmentVariable("OPENCLAW_DATA_DIR", "D:\\OpenClawData", "User") # 设置系统级环境变量（需要管理员身份的 PowerShell） [Environment]::SetEnvironmentVariable("OPENCLAW_DEBUG", "1", "Machine")注意 PowerShell 中反斜杠的转义问题。在SetEnvironmentVariable的字符串参数里，"D:\\OpenClawData"中的\\会被解析为单个\，如果你写成"D:\OpenClawData"，PowerShell 会把\O当作转义字符处理，导致路径错误。
配置完之后，有一个很多人都会忽略的步骤：重启终端窗口。环境变量是在进程启动时读取的，当前已打开的终端不会自动刷新新值。你可以通过echo $env:OPENCLAW_MODEL_BASE_URL来验证是否生效。
如果你偏好 CMD（命令提示符），也可以使用setx命令，但它有两个缺点：一是setx会截断超过 1024 字符的值，二是它只在新的进程中生效，当前窗口也不会更新。所以在 Windows 上，我更推荐 PowerShell 的方式。
3.2 macOS 下需要格外注意 shell 差异
macOS 的环境变量配置，首先要分清你用的 shell 是 zsh 还是 bash。自从 macOS Catalina 开始，系统的默认 shell 已经换成了 zsh，也就是说你大概率需要修改的是~/.zshrc文件，而不是网上很多旧教程里写的~/.bash_profile。
打开终端，用文本编辑器编辑配置文件：
# 对于使用 zsh 的 macOS 用户 nano ~/.zshrc然后往里面追加以下内容：
# OpenClaw 环境变量配置 export OPENCLAW_MODEL_BASE_URL="http://localhost:11434/v1" export OPENCLAW_API_KEY="your-key-here" export OPENCLAW_MODEL_NAME="qwen2.5:7b" export OPENCLAW_DATA_DIR="$HOME/OpenClawData" export OPENCLAW_MODE="interactive" export OPENCLAW_DEBUG="0"保存退出后，执行source ~/.zshrc让配置立即生效。这里要注意，source命令只对当前终端会话有效，新开的终端窗口也会自动加载.zshrc，所以如果你开了多个终端，需要在每个终端里重新source一次，或者干脆关掉重开。
macOS 下还有个特殊场景：如果你从应用商店或官网下载的软件不是通过终端启动的，比如将 OpenClaw 打包成了.app，那么它启动时不会读取~/.zshrc。这是 macOS 图形化应用与命令行应用之间的机制差异。解决方法是使用launchctl setenv设置用户级环境变量：
launchctl setenv OPENCLAW_MODEL_BASE_URL "http://localhost:11434/v1" launchctl setenv OPENCLAW_API_KEY "your-key-here"通过launchctl setenv设置的值，可以被通过 Finder 启动的图形应用继承到，但需要注意的是，这种方式在系统重启后不会保留，需要写在启动脚本或 LaunchAgent 中才能持久化。对大多数从终端运行 OpenClaw 的用户来说，改.zshrc就已经足够了。
3.3 Linux（主流发行版）几种常见部署方式
Linux 下的配置方法取决于你打算怎么运行 OpenClaw，我把它分成三种场景来讨论。
第一种是最直接的：在交互式终端里直接运行。这时需要把变量写入~/.bashrc（绝大多数发行版默认 bash）或~/.zshrc（如果你手动切换了 zsh）。写法和 macOS 一致，但要注意，在某些精简版系统（比如 Docker 容器内）可能没有.bashrc文件，需要先创建：
touch ~/.bashrc echo 'export OPENCLAW_MODEL_BASE_URL="http://localhost:11434/v1"' >> ~/.bashrc echo 'export OPENCLAW_API_KEY="your-key-here"' >> ~/.bashrc source ~/.bashrc第二种场景是通过 systemd 服务管理。如果你希望 OpenClaw 作为开机自启的后台服务运行，那就不能依赖用户 shell 配置了，因为 systemd 服务默认不加载.bashrc或.profile。正确的做法是在 service 文件中使用EnvironmentFile指向一个独立的配置文件：
# /etc/systemd/system/openclaw.service 内容示例 [Unit] Description=OpenClaw Service After=network.target [Service] Type=simple User=yourname EnvironmentFile=/etc/openclaw/env ExecStart=/usr/local/bin/openclaw serve Restart=on-failure [Install] WantedBy=multi-user.target然后创建对应的环境变量文件/etc/openclaw/env：
OPENCLAW_MODEL_BASE_URL=http://localhost:11434/v1 OPENCLAW_API_KEY=your-key-here OPENCLAW_DATA_DIR=/var/lib/openclaw OPENCLAW_MODE=service注意这个文件里不能有export前缀，也不能有引号包裹（除非值本身包含空格等特殊字符），这是 systemd 环境文件的语法要求。写完文件后，需要执行sudo systemctl daemon-reload再重启服务，新变量才会被加载。
第三种场景是 Docker 容器运行。这个相对简单，因为 Docker 容器的环境变量天生是标准化的。在docker run时使用-e参数，或者更推荐在docker-compose.yml里使用environment小节统一管理：
services: openclaw: image: openclaw:latest container_name: openclaw environment: - OPENCLAW_MODEL_BASE_URL=http://host.docker.internal:11434/v1 - OPENCLAW_API_KEY=your-key-here - OPENCLAW_DATA_DIR=/data volumes: - ./openclaw-data:/data这里需要特别提一点：容器内访问宿主机上的 Ollama 服务时，localhost指向的是容器自身，而不是宿主机。Linux 下需要从宿主机获取 Docker 网桥的 IP 地址（通常是172.17.0.1），或者改用network_mode: host；在 Docker Desktop 场景下则可以使用host.docker.internal这个特殊的域名。这个细节一旦搞错，你会看到 OpenClaw 反复提示“连接超时”，但在容器内测试一切看起来又很正常，极具迷惑性。
4. 核心原理与实际踩坑：为什么你的配置总是不生效
4.1 子进程继承机制与常见的“伪生效”现象
环境变量在 Unix 系统中的传递机制是“父进程传给子进程”，这意味着一系列连锁反应。当你启动 OpenClaw 后，它如果又拉起了其他子进程（比如调用 Ollama 的 SDK 或启动本地推理进程），这些子进程会继承 OpenClaw 进程的环境变量。这本来是好事，但也会带来一个坑：你在终端里export了变量，只对当前 shell 及它启动的子进程有效，对系统其他无关进程没有影响。
我在实际部署中遇到过这样一次“伪生效”情况：某一次我在终端 A 里配好了全部变量，OpenClaw 能正常运行；但当我用另一个方式启动（比如通过系统服务）时，日志里报出 API Key 无效。原因就是两种启动方式继承了不同的环境变量集合。排查方法也很简单：分别在不同启动方式下打印关键变量的值，做一个对比，而不是假设“我在机器上已经配置过了”。
4.2 常见三大误区：大小写、特殊字符、换行符
第一个误区是大小写。Linux 和 macOS 的环境变量是大小写敏感的，openclaw_api_key与OPENCLAW_API_KEY是两个完全不同的变量。但在 Windows 上，旧版 CMD 和部分程序的环境变量查找是不区分大小写的，这导致很多人在 Windows 上配置时养成了随意大小写的习惯，一旦切到 Linux 就立马翻车。我的建议是，无论你在哪个系统上，都统一使用程序文档中给出的全大写命名。
第二个误区是特殊字符。API 密钥或代理地址中如果包含$、#、空格、引号等字符，在.bashrc或.zshrc中不加以处理就会出问题。比如密钥值是abc$123，在双引号内$123会被当作变量展开（得到一个空值），结果你的密钥就变成了abc。正确做法是使用单引号来包裹这类变量值，或者在特殊字符前加转义符：
export OPENCLAW_API_KEY='abc$123'第三个误区是换行符。如果你在 Windows 上用记事本编辑了.env或.bashrc文件，然后拷贝到 Linux 服务器上使用，文件中的换行符（CRLF）可能会导致解析失败。解决方法也很简单：在 Linux 上执行sed -i 's/\r$//' ~/.bashrc去除回车符，或者在 Windows 上使用支持 Unix 换行符的编辑器（如 VS Code）保存文件。
4.3 验证配置是否生效的通用方法
配置完成后，不要急着启动 OpenClaw，先花 30 秒做一个快速验证。在终端中执行以下命令查看变量是否被正确识别：
# Unix 系 echo $OPENCLAW_MODEL_BASE_URL echo $OPENCLAW_API_KEY # Windows PowerShell echo $env:OPENCLAW_MODEL_BASE_URL echo $env:OPENCLAW_API_KEY如果输出为空，说明变量没有加载成功；如果输出为乱码或包含\r之类的字符，则说明文件格式或编码存在问题。还有一个更高级的验证方法：直接启动一个测试用的子进程来检查：
env | grep OPENCLAW这条命令会列出当前环境中所有名称包含OPENCLAW的变量，你一眼就能看出哪些已经生效、哪些值有问题。测试完确认无误后，再运行 OpenClaw 也不迟。
5. 常见问题与排查技巧实录
5.1 快速排查清单
我在反复部署和帮助他人排查的过程中，整理了一份问题排查清单，按顺序执行可以解决绝大多数环境变量不生效的问题。
检查变量名拼写。目标工具文档中的变量名是否与你配置的一致？首字母大小写、是否有下划线、是否多打了空格？这一步看起来简单，出错率却极高。
确认配置文件被正确加载。在终端中运行
echo $SHELL查看当前 shell 类型，再确认你修改的是对应 shell 的配置文件。zsh 用户改了.bashrc是完全无效的。检查配置文件是否有语法错误。执行
bash -n ~/.bashrc或zsh -n ~/.zshrc可以检查语法。有时一个多余的空格或引号未闭合，会导致整段配置被跳过。确认变量在当前进程中被导出。执行
env | grep OPENCLAW，如果输出为空，尝试source配置文件后再查一次。检查程序启动方式是否绕过了配置文件。如果你是通过 systemd 或 launchd 启动的，那用户 shell 配置天然不生效，必须使用第三节中对应的方法配置。
查看程序日志中实际读取到的值。打开 OpenClaw 的调试模式（
OPENCLAW_DEBUG=1），查看启动日志中打印的配置项，这能直观地看出程序实际使用了哪个值。如果日志中打印的地址和你配置文件里的不一致，一定是优先级或加载顺序问题。
5.2 一个真实案例：macOS 上“明明配置了却连不上”
有一次我在 macOS 上部署 OpenClaw，配置好~/.zshrc并source之后，程序还是提示无法连接模型服务。我一度怀疑是 Ollama 没启动，但用 curl 手动访问http://localhost:11434又是通的。
后来我静下心来排查，发现我在终端中运行的命令是nohup openclaw serve &，而nohup启动的进程虽然继承了当前 shell 的环境变量，但它把标准输出重定向到了文件里，我在另一个终端看到的警告信息其实不是程序的第一条输出。真正的问题在于，我配置变量时把OPENCLAW_MODEL_BASE_URL敲成了OPENCLAW_MODEL_BASE-URL（下划线写成了连字符），程序在启动时静默地忽略了这个未知变量，然后使用了内置默认值http://127.0.0.1:8080，自然连不上 Ollama。
这个案例告诉我们，配置出现问题时，与其反复猜测，不如直接打印程序日志和当前环境变量的交集。现在我会第一时间在 OpenClaw 的调试日志中搜索OPENCLAW前缀，确认程序实际读取的每一项配置。
5.3 关于使用.env文件的补充建议
无论你运行在哪个系统上，如果 OpenClaw 官方支持.env文件（也就是从文件自动加载环境变量的机制），我强烈建议你优先使用这种方式。原因有三个：一是.env文件格式简单，KEY=VALUE每行一个，便于阅读和版本管理；二是它不受 shell 类型影响，不管你用什么启动器都能统一加载；三是它可以放进项目目录里，与代码一起分发，团队协作时不用每个人都去设置系统级环境变量。
一个典型的.env文件内容如下：
# OpenClaw Environment Configuration OPENCLAW_MODEL_BASE_URL=http://localhost:11434/v1 OPENCLAW_API_KEY=your-key-here OPENCLAW_MODEL_NAME=qwen2.5:7b OPENCLAW_DATA_DIR=/home/yourname/openclaw-data OPENCLAW_MODE=interactive OPENCLAW_DEBUG=1使用.env文件时，有一点要特别记住：不要把这个文件提交到公开的代码仓库里，尤其是其中包含 API 密钥时。正确做法是在项目根目录添加.gitignore并写入.env一行，同时准备一个.env.example文件作为模板，把真实的密钥留空，让团队成员自行复制并填写。
5.4 环境变量管理工具横向对比
如果你管理的项目多了，或者需要在多个配置方案之间来回切换，手写export的方式就会显得笨拙。我在不同场景下用过几种方案，这里做一个简单对比：
| 工具/方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
系统级环境变量（系统设置//etc/environment） | 全局生效，所有用户和进程可见 | 修改需要重启或重新登录，影响范围大 | 固定不变的公共配置 |
Shell 配置文件（~/.bashrc） | 修改即时生效，粒度到用户级 | 只对当前 shell 生效，跨系统不通用 | 个人开发调试 |
.env文件 + 加载器 | 随项目走，配置清晰，便于版本控制 | 需要额外配置加载器，无法覆盖系统环境变量 | 项目级别配置管理 |
| 容器环境变量 | 隔离性最好，配置不可更改 | 只能在容器构建或启动时注入，运行后难以修改 | Docker 部署 |
就 OpenClaw 的场景来说，我个人的推荐组合是：开发调试时用.env文件，因为试错成本低、局部生效；正式部署到服务器时，根据启动方式选择 systemd 的EnvironmentFile或者容器的 environment 配置，保证服务重启后配置依然可靠。
6. 最后的补充：跨平台环境变量标准化与安全问题
6.1 配置的一致性策略
跨平台部署 OpenClaw 时，你可能会遇到一个现实问题：同一套配置在不同系统下，文件路径写法完全不同。Windows 是D:\OpenClawData，macOS/Linux 是/Users/name/openclaw-data。如果配置文件写死了绝对路径，跨系统就没法直接复用。
我的应对策略是：在配置中使用系统相关的默认路径变量，而不是写死绝对路径。比如 Linux/macOS 下设置OPENCLAW_DATA_DIR="$HOME/openclaw-data"，Windows 下设置OPENCLAW_DATA_DIR="%USERPROFILE%\openclaw-data"（或者在 PowerShell 里使用$HOME/openclaw-data）。这样无论用户名是什么，配置都能正确解析。如果你使用.env文件，也可以利用进程的工作目录作为相对路径的基准，但这要求程序必须在固定目录下启动，否则会有不确定性，因此还是推荐明确使用绝对路径或系统变量拼接。
6.2 API 密钥的安全存储小技巧
API 密钥是环境变量配置中最敏感的信息。尽管环境变量已经是比硬编码在代码里好得多的方案，但如果你把密钥写在~/.bashrc里，任何能够读取你用户目录文件的进程都有机会获取到它。以下是我在实际使用中总结的几条安全建议：
- 避免将含密钥的
.env文件提交到 Git 仓库，即使仓库是私有的也不建议。 - 如果需要共享配置模板，把真实密钥用占位符代替，并提供生成密钥的指引。
- 在服务器上使用 systemd 部署时，给
EnvironmentFile设置严格的权限，比如sudo chmod 600 /etc/openclaw/env，确保只有 root 和你指定的用户能读取。 - 定期轮换密钥，不要把同一个密钥长期用于多个环境。虽然这看起来增加了管理工作量，但一旦某个环境被突破，影响面能被有效控制。
6.3 测试驱动配置：用最小配置跑通再逐步加参数
最后分享一个我屡试不爽的方法：第一次配置环境变量时，不要一次性把所有参数都填上。先用最小配置（只设置OPENCLAW_MODEL_BASE_URL和OPENCLAW_API_KEY）尝试启动，确认程序能正常连接模型服务。跑通之后，再逐个添加其他变量，比如数据目录、调试开关、运行模式等。
这样做的好处是，一旦出现问题，你能明确知道是新加的哪个变量导致的，而不是在一堆配置里大海捞针。环境变量虽小，但确实是整个本地部署过程中的基石，把基础打牢了，后面的模型加载、工具调用、任务执行才能少折腾。希望这些经验能帮你顺利把 OpenClaw 跑起来，如果配置过程中有其他心得，也欢迎一起交流。
