部署之前我先说一句这个OpenClaw踩坑之旅我是在三台机器上“完整走完”的。公司配的Windows台式机、自己日常用的MacBook ProApple Silicon、还有一台当服务器用的Linux工作站。第一遍部署三个平台全军覆没没有一个是照着官方文档敲完命令就能直接跑的。Windows卡在Docker Desktop的安装姿势macOS卡在Homebrew和内存吃紧Linux则卡在一堆“看得到但查不明白”的系统依赖缺失。所以这篇保姆级教程是我把三平台各自遇到的问题整理成一张完整的踩坑地图按Windows/Mac/Linux分平台展开再把三平台共通的坑单独拿出来讲。无论你是第一次听说OpenClaw还是已经部署过但卡在某一步这篇应该都能帮你省下大量排查时间。1. 部署前必须想清楚的底层逻辑OpenClaw到底依赖什么很多人一上来就急着装OpenClaw结果报错了才回头查依赖。我建议你先花十分钟搞清楚一件事你要装的这个东西本质是一个“调度层”不是一个纯粹的模型运行时。它自己不带大模型推理能力需要后端推理服务最常见的是Ollama先把模型跑起来OpenClaw再去调用这些模型完成各类任务。嘴上说的是“部署OpenClaw”实际上一整条链路是操作系统 → 容器/运行时 → Ollama → 模型文件 → OpenClaw。哪一环出了问题都会表现为OpenClaw起不来。1.1 OpenClaw的“引擎控制器”架构先理解再动手我用一个相对好懂的类比来解释Ollama这类推理后端相当于发动机负责把模型真正“转起来”OpenClaw相当于方向盘、仪表盘和驾驶员负责决定“我该怎么调用这台发动机”。没有发动机方向盘只是装饰没有控制器发动机也只是空转。所以在部署时官方文档里除了OpenClaw本身的安装步骤通常还会要求你准备一个推理后端、确认模型文件路径、配置好调用接口。这三个东西分别对应三类问题推理后端能不能提供稳定的API服务模型文件是否完整下载且格式正确OpenClaw的配置文件里指向的后端地址和模型名是否正确。我最开始踩的坑就是跳过验证后端直接跑OpenClaw结果日志里全是连接失败最后才发现Ollama根本没有成功启动。所以我建议所有人在动手之前先按这个链路逐层检查不要一锅端。1.2 三平台差异的本质不是OpenClaw的锅而是操作系统自身的脾气OpenClaw本身是跨平台的但它依赖的底层组件在三个系统上的行为差别很大。Windows的进程模型、路径分隔符、权限系统和Linux天生不一样macOS虽然底层是Unix但Apple Silicon的GPU加速栈是Metal而不是CUDA很多在Linux上理所当然的GPU支持在macOS上走的是另一条路Linux倒是和容器最亲但容器跑起来之后GPU直通、自启动服务、权限管理又各有各的坑。我把三平台主要差异整理成一张对照表后面每一节还会展开讲。对比项WindowsmacOSLinux推荐部署方式WSL2 Docker Desktop本机进程 OllamaMetal加速Docker 或 systemd 服务GPU 加速通过 WSL2 透传配置复杂Metal/MPSOllama 默认支持NVIDIA Container Toolkit服务自启任务计划程序/Docker Desktop 自启launchd / Homebrew Servicessystemd典型路径风格C:\Users... 盘符绝对路径/Users/xxx/.../home/xxx/...最容易翻车的点Docker Desktop 安装姿势、中文目录Homebrew 环境、内存压力缺失系统库、权限、systemd 上下文1.3 版本选择先跑通最小流程再追新版本另一个建议是不要一开始就上最新版本。无论哪个平台先拉一个稳定版本一般是官方仓库里标记为latest release或stable的版本配合一个小体积模型先跑通完整链路。我三台机器第一轮部署全失败一半原因就是我手里拿的是当时最新的开发版日志报错和网上搜到的问题对不上号。先用稳定版建立“能跑起来”的基线之后再考虑升级或切换新特性排查范围会小很多。2. Windows平台80%的坑集中在Docker Desktop安装姿势和路径习惯上Windows是我踩坑最多的平台原因是Windows本身的“双面性”你既可以把OpenClaw直接跑在原生Windows环境也可以放进WSL2里跑Linux子系统。两种方案各有各的麻烦。2.1 WSL2方案还是原生Windows方案我的实测结论如果只看官方文档Windows下OpenClaw的部署路径往往写得比较模糊很多脚本默认你在Linux环境。所以我的建议非常明确除非你非常清楚自己在做什么否则优先选WSL2 Docker这条路。原因有三Docker Desktop在Windows上本身就是基于WSL2后端运行的与其绕开它不如直接用OpenClaw的多数示例命令、配置路径、权限模型都是按Linux写的放在WSL2里几乎零水土不服后续如果遇到权限问题、目录挂载问题起码你能在同一个文件系统下排查而不是在Windows和Linux边界上反复横跳。WSL2安装本身不算难但有几个细节必须先确认在“启用或关闭Windows功能”里勾选“适用于Linux的Windows子系统”和“虚拟机平台”重启在Microsoft Store安装Ubuntu 22.04或24.04 LTS打开终端后设置默认用户密码执行wsl --set-version 发行版名称 2切换到WSL2在任务管理器“性能”标签页确认“虚拟化”已启用。2.2 Docker Desktop安装时的三个致命细节Docker Desktop看起来就是一个普通的Windows应用程序双击安装就行但三个细节踩一个就得重来。第一安装前必须确认WSL2已经设置完成否则Docker Desktop虽然能装上但引擎起不来日志里常见的报错是“Docker Desktop requires a newer WSL kernel version”。第二安装完成后进入Settings → General必须勾选“Use the WSL 2 based engine”。这个选项在某些安装版本里默认不勾没有它容器全部跑在Hyper-V虚拟机里和WSL2的文件互通基本是摆设。第三设置里记得把磁盘镜像位置放回Docker Desktop管理。很多人会在Settings → Resources里调整WSL虚拟磁盘的位置这个没问题但如果你把工作目录放在Windows盘符下的中文路径里后面挂载到容器时会碰到一堆编码和路径分隔符问题这个我下一节单独说。装完之后先别急着拉OpenClaw跑一个验收命令docker run --rm hello-world能正常打印Welcome信息说明Docker Engine和WSL2后端已经通了。2.3 中文用户名与路径最容易忽略却最致命的坑Windows上最常见的隐藏炸弹是用户名是中文的。比如你的Windows用户目录是C:\Users\张三WSL2里对应的挂载路径是/mnt/c/Users/张三这时如果你把OpenClaw的数据目录放到用户目录下配置文件里但凡出现中文路径轻则警告重则直接找不到文件。更麻烦的是Docker Desktop在共享文件夹时对特殊字符和空格的处理不够稳定OpenClaw容器会莫名其妙地拒绝挂载。我的做法是在Windows下建一个纯英文的专用工作目录比如D:\openclaw-work在WSL2里通过/mnt/d/openclaw-work访问。所有模型文件、配置文件、日志目录都放这里。这样既能利用Windows的大磁盘又能让Linux路径保持干净。同时在Windows终端里执行命令时J路径分隔符的处理也容易出问题。比如某些脚本会写D:\openclaw-work\config\config.yaml但到了WSL2里必须写成/mnt/d/openclaw-work/config/config.yaml。这个转换不要靠人肉记建议在WSL2里建一个软链接指向常用工作目录ln -s /mnt/d/openclaw-work ~/openclaw-work之后所有命令只需要操作~/openclaw-work即可。2.4 终端选不对命令天然跑不动Windows下我见过太多人卡在“明明命令敲对了却报错”上。最常见的原因是终端和脚本的换行符不一致。你在Windows笔记本上编辑过的.sh脚本默认可能是CRLF行尾拿到WSL2里执行时会出现/usr/bin/env: ‘bash\r’: No such file or directory一类的报错。我建议统一用Windows Terminal新建一个Ubuntu终端的标签页然后在WSL2里执行git config --global core.autocrlf input这样从Git仓库拉下来的脚本就不会变成CRLF。另外脚本执行失败时第一反应先查文件格式file update.sh cat -A update.sh | head -20看到^M$结尾的就是CRLF用sed -i s/\r$// update.sh或dos2unix update.sh转一下就好。3. macOSApple Silicon和Homebrew是两大主战场macOS的部署体验整体比Windows顺麻烦主要集中在你得先解决两件事芯片平台和Homebrew环境。这两个不处理好后面所有命令都像踩在棉花上。3.1 Intel和Apple Silicon的部署差异不是所有教程都适用Apple SiliconM系列芯片和Intel Mac在部署OpenClaw时路径完全不同。M系列芯片的GPU核心走的是Metal接口Ollama对Metal的支持是目前几个主流推理后端里做得最顺的基本装上就能用GPU加速。Intel Mac则大多靠CPU硬扛内存小的情况下跑大一点模型很容易力不从心。先确认你的芯片类型点击左上角苹果图标 → 关于本机看“芯片”一栏。如果写着Apple M1/M2/M3/M4下面所有命令按Apple Silicon路径走如果写Intel做好纯CPU运行的准备。Ollama在macOS上的安装很简单最简单的方式是下载官方安装包或者用Homebrew安装。安装完之后用ollama run llama3.2:1b这一类小模型验证一下推理能正常对话就说明后端没问题。注意在“系统设置 → 隐私与安全性”里首次运行Ollama时可能会弹“允许网络连接”要选择允许否则API端口只监听本地回环OpenClaw连不上。3.2 Homebrew安装失败大部分不是网络问题是环境问题macOS上很多人第一步就栽在Homebrew。装不上的原因千奇百怪但最常见的是缺少Xcode Command Line Tools。没有它编译类依赖全部失败。我的建议是先单独安装Xcode Command Line Toolsxcode-select --install安装过程中会弹窗等它跑完。然后用系统自带的/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)装Homebrew。装完以后立刻检查路径Apple Silicon机器上Homebrew装在/opt/homebrew必须把/opt/homebrew/bin加进PATHIntel Mac上位置是/usr/local/bin这个通常已经默认在PATH里。检查方式brew --prefix如果输出/opt/homebrew说明装对了如果输出一个不存在的路径或者命令找不到就手动编辑~/.zshrc加上export PATH/opt/homebrew/bin:$PATH3.3 Metal GPU加速性能差距可能不是玄学是没配好同样一个模型在Apple Silicon上跑和Intel Mac上跑完全两个体验。M系列芯片的优势就在于Ollama会默认用Metal后端把模型放到GPU上跑。你可以打开活动监视器在“GPU”一栏看运行ollama run命令时的GPU占用。如果GPU占用率一直是0%说明Metal后端没有生效最常见的原因是你下载了Intel版Ollama或者系统版本太老。另外一个容易忽略的问题是内存压力。macOS的统一内存架构意味着模型占用内存时GPU和CPU共享同一块物理内存。8GB内存的M1机器跑1B到3B参数的小模型勉强可以再大就会疯狂换页整个系统卡到怀疑人生。我的建议是8GB内存跑1B、3B级别模型16GB内存再考虑7B更大的模型别在Mac上硬试。3.4 磁盘占用和“删不干净”的旧模型Ollama拉取的模型文件默认放在~/.ollama/models一个7B模型动辄4到5GB装了三五个模型以后磁盘就见底了。我的习惯是定期检查ollama list看哪些模型不再用直接ollama rm 模型名删掉。如果实在要大模型又不想占本地空间可以考虑把OLLAMA_MODELS环境变量指到外置SSD或另一个磁盘分区export OLLAMA_MODELS/Volumes/SSD/ollama-models注意这个变量要在Ollama服务启动前设置好否则不生效。4. Linux跑起来最顺但坑全藏在“服务化”和“权限”里Linux平台对OpenClaw来说应该是“主场”容器、命令行、权限模型全都顺滑。但我实际部署时发现坑不在于OpenClaw本身而在于大多数教程默认你有一个完整的桌面系统然而真实服务器往往是最小化安装缺了一堆基础依赖。4.1 最小化系统的依赖缺失报错让你猜谜在干净的Ubuntu Server上部署OpenClaw时第一步就可能遇到git: command not found、curl: command not found这类基础问题。但更隐蔽的是缺编译工具链。有个做法很推荐提前把常用工具一次性装齐sudo apt update sudo apt install -y curl git build-essential unzip如果OpenClaw需要从源码编译某些组件build-essential几乎必装。另外我遇到过Python相关依赖缺失的情况一个脚本报ModuleNotFoundError: No module named yaml这时不要瞎猜直接看脚本头部声明的是哪个Python环境再用对应的包管理器安装。排查动态库缺失也有一个很实用的命令ldd /usr/local/bin/openclaw如果输出里有not found就用apt-file search或dpkg -S找对应的库属于哪个包。用ldd直接定位缺失项比盯着报错日志盲猜效率高一个量级。4.2 systemd自启动配置别让OpenClaw随终端关闭而退出很多人一开始在终端里前台启动OpenClaw跑通了以为完事了。结果一旦关掉SSH会话服务跟着就没了。上线服务必须用systemd托管。下面是一个经过实际调整后的service单元文件作为参考路径和用户请根据实际情况替换以你安装的版本和配置为准[Unit] DescriptionOpenClaw Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Useryouruser Groupyouruser WorkingDirectory/home/youruser/openclaw-work EnvironmentOLLAMA_HOST127.0.0.1:11434 ExecStart/usr/local/bin/openclaw serve Restartalways RestartSec5 [Install] WantedBymulti-user.target写完放到/etc/systemd/system/openclaw.service然后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw查看状态和日志systemctl status openclaw journalctl -u openclaw -f值得注意的一点是Restartalways。OpenClaw如果因为Ollama暂时未就绪而退出systemd会自动帮你拉起来这个在Windows和macOS上配置起来麻烦得多。4.3 为什么不该用root跑日常服务以及目录权限的正确姿势Linux部署时最容易走捷径的就是直接sudo root跑。大多数情况下能跑通但后续会埋雷OpenClaw创建的缓存和数据目录归root所有以后用普通用户更新或备份时会报权限拒绝。我建议专门建一个运行用户比如sudo useradd -m -s /bin/bash openclaw sudo mkdir -p /home/openclaw/openclaw-work sudo chown -R openclaw:openclaw /home/openclaw然后把systemd的User和Group改成openclaw。以后所有日志、缓存、配置都在这个用户下产生备份和迁移都很干净。4.4 GPU容器运行时Docker能跑但GPU用不上等于白装Linux服务器如果装了NVIDIA显卡很多人会直接docker run拉OpenClaw镜像然后发现性能差得离谱——因为容器里根本没有GPU透传。要让Docker容器访问宿主的NVIDIA GPU需要装NVIDIA Container Toolkitsudo apt install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker验证方式docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi容器内能输出显卡信息才算打通。没有NVIDIA GPU的机器老老实实用CPU方案也可以跑小模型只是响应速度慢不少。5. 三平台共通的四个坑端口、防火墙、环境和升级分平台讲完之后我把所有平台都踩过一遍的共性坑汇总一下。这些问题的表象各有不同但根源几乎都是同一个套路。5.1 端口占用日志里最像“没安装好”的假象OpenClaw连接Ollama时默认端口通常是11434Web界面或API服务常用的端口是8080、3000、8000。最让人抓狂的是端口被占时日志提示是“connection refused timeout connection reset”之类的模糊错误比如“failed to connect to localhost:11434”。排查方法按平台分三条命令Windowsnetstat -ano | findstr 11434macOS/Linuxlsof -i :11434或ss -tulpn | grep 11434找到占用端口的进程后先看它是不是Ollama本身。如果Ollama没启动但端口被占用通常是你之前手动启动过另一个实例。解决办法要么杀掉占用进程要么给Ollama换端口export OLLAMA_HOST127.0.0.1:11435然后让OpenClaw的配置指向新端口。端口问题排查熟练之后很多“起不来”的假象会解开。5.2 局域网访问时的防火墙与共享目录很多人部署完以后想在另一台电脑上通过局域网IP访问OpenClaw的Web界面结果发现从局域网访问不了。原因多半不是OpenClaw配置问题而是系统防火墙拦了端口。Windows上常见的是防火墙弹窗没有点“允许”macOS上常见的是之前提到的“允许网络连接”没开Linux上则是ufw默认拒绝外部访问。Linux上最直接的做法sudo ufw allow 8080/tcp sudo ufw allow 11434/tcp另外OpenClaw如果配置成只监听127.0.0.1外部也一样访问不了。需要把监听地址改成0.0.0.0但这么做要考虑局域网内的安全风险不建议在公共网络下这样放开。5.3 配置文件的绝对路径和换行符隐藏的环境变量杀手三平台部署OpenClaw时配置文件里的路径风格完全不同。Windows原生命令与Linux命令、macOS的路径之间都有一个共性要求绝对路径要写对。我见过很多人在Windows的PowerShell里手滑把路径写成C:\Users\...然后进了WSL2环境依然复制粘贴结果Docker容器内根本没有这个路径。另一个高频问题是config.yaml这类配置文件的缩进和换行符。macOS和Linux没问题但如果你在Windows上编辑过配置再传到Linux服务器上很可能因CRLF行尾导致YAML解析失败。共享给跨平台环境使用的文件最好用dos2unix统一转换一遍或者在编辑器里强制UTF-8无BOM LF。5.4 版本升级的两条铁律备份配置看升级日志OpenClaw更新版本是另一个灾难高发区。我见过太多人直接下载新版本覆盖旧文件结果启动时配置格式不兼容、依赖版本冲突最后只能回滚。我的建议是升级前先备份配置和数据目录。比如把整个openclaw-work目录打包tar -czf openclaw-backup.tar.gz ~/openclaw-work升级完成后如果服务起不来第一件事不是卸载重装而是查看完整启动日志比如Linux上执行journalctl -u openclaw -n 100。多数升级失败是版本之间的配置文件格式变化引起的日志里一般会明确提示哪一项配置不识别。6. 部署完成后别急着上节目实测调优与验收三个平台都跑通之后别高兴太早。我建议按下面几条把最终配置固定下来方便以后统一管理和迁移。6.1 模型响应和并发调优模型推理性能和OpenClaw本身关系不大更多取决于后端Ollama和硬件资源。可以留意Ollama的运行时参数比如上下文长度、并发请求数、num_ctx等这些参数直接影响响应速度。8GB内存的机器上下文长度不要设太大否则内存很快吃满。我的习惯是先跑一个小模型确认整体延迟再逐步增大上下文长度找到一个不卡顿的临界值。如果打开Web界面时响应感很慢优先检查内存压力而不是网速。6.2 三平台部署对照表最终配置建议平台推荐运行方式模型后端服务自启方式最需要记住的一条WindowsWSL2 Docker DesktopOllamaWSL2内Docker Desktop 开机自启不要放中文路径macOS本机进程OllamaMetal加速brew services start ollama内存优先给小模型Linuxsystemd DockerOllamaCPU或GPUsystemctl enable openclaw用普通用户跑不用root6.3 从零到一的可复现验收清单无论哪个平台都建议按照下面的顺序走一遍每一步都有明确的验证点确认硬件和系统版本芯片、内存、虚拟化开关安装并验证基础环境Docker/WSL2/Homebrew/依赖库安装推理后端拉取一个小模型用ollama run验证能对话验证API端口可访问curl http://127.0.0.1:11434/api/tags启动OpenClaw确认它能连上Ollama通过OpenClaw调用一次模型完成一个极简任务配置开机自启或服务托管备份整个工作目录并记录当前版本号。每一步都通过后再进入下一步基本能避免“整个环境到了最后一步才发现前面漏了某个配置”的窘境。6.4 日志与日常维护的顺手技巧最后说几个日常维护顺手心得。日志是排障第一利器。Windows上Docker Desktop的日志在容器内可以用docker logs看macOS的Ollama日志可以看~/.ollama/logsLinux上统一的journalctl -u openclaw就够了。不要等到卡死了才去看日志平时在刚启动服务时就扫一眼能发现不少隐藏警告。备份备份备份。我自己的习惯是每两周打包一次工作目录和配置文件并且同时保留上一份备份。万一升级失败回滚到上一份备份通常比现场排查快得多。数据迁移时比如从Windows换到Linux不要把整个配置原封不懂地拷贝过去。路径差异、换行符差异、版本差异都可能导致配置失效。正确做法是拷贝一套干净配置只手动迁移其中有价值的部分比如自定义工具配置、API密钥、模型列表。最后分享一点个人体会三台机器全部跑通之后我最大的感触是真正耗时间的从来不是OpenClaw本身而是“消除三个操作系统之间的环境差异”。如果你也准备部署建议一定按“最小运行链验证 → 服务化 → 多平台复用”的顺序来别一上来就追求完整功能。先让一个小模型在最简配置下跑起来再逐步加东西这种方式的排障效率远超一遍遍翻教程。还有一个我后来一直在用的小技巧在三台机器上统一把工作目录都命名为openclaw-workLinux路径是/home/xxx/openclaw-workmacOS路径是/Users/xxx/openclaw-workWindows内部则统一映射到D:\openclaw-work。目录名一致配置文件里的路径替换量大幅减少跨平台迁移时也少很多折腾。希望这份踩坑地图能帮你少走一些弯路。