2. 环境准备方案的整体设计与选型思路2.1 为什么环境准备是OpenClaw安装的“第一道坎”很多朋友拿到OpenClaw第一反应是直接git clone然后pip install结果装到一半被各种报错劝退。我见过太多次这样的场景代码拉下来了依赖装了十分钟最后卡在一个libffi或者OpenSSL的版本问题上怎么折腾都过不去最后只能重装系统。其实问题根本不在你的操作而在环境准备这一步没做到位。OpenClaw这类工具和其他普通Python项目有个本质区别它对底层系统环境的要求比一般应用高不少。它不只是跑一段逻辑代码而是要调用本机的各种能力接口——比如音频解码、图像处理、消息推送还要和系统的Shell交互。这些能力不是pip装个包就能解决的它们依赖的是一些C语言编译的动态库、系统的底层组件。如果环境准备这一步没有把这些底子打好后面装什么都会磕磕绊绊。我自己的习惯是拿到一个新项目先不急着装花二十分钟把环境梳理一遍。这二十分钟花得非常值它能帮你避免之后两三个小时的排错时间。而且环境准备好一次之后不仅OpenClaw能用以后装别的同类型项目都会顺利很多。2.2 三种部署方式为什么推荐源码安装OpenClaw的常见部署方式有几种直接下载发行版压缩包、用包管理器安装、从源码安装。我自己试过前两种后来一直用的是源码安装原因很简单——发行版也好、镜像包也好它们都封装好了方便是方便但一旦你想改配置、换模型接口、加自定义插件就会觉得束手束脚。用包管理器安装的问题在于很多依赖版本被固定住了看起来装完了实际上某些子依赖的版本是旧版和当前系统不完全匹配。你运行OpenClaw的时候它不会立刻报错但是跑到某个具体功能时会突然崩溃这种问题是最难排查的。源码安装反而是最稳的一条路。它看起来步骤多一点但实际上每一步都可以控制出了问题你能定位到具体环节。环境准备的核心思路就是为这种可控性服务的先把系统工具链配好再把Python环境隔离好最后拉代码装依赖。每一层都清清楚楚出了问题你知道去哪查。我推荐有动手能力的朋友都走源码安装这条路。如果你是第一次接触这块也不用慌接下来我拆开一步一步讲跟着做就行。2.3 环境准备的核心思路三个层面一次搞定我把整个环境准备拆成三个层面这个思路在解决同类问题时也通用。第一层是系统级环境。包括操作系统的基础组件、编译工具链、需要用到的系统库。这一层解决的是“OpenClaw能不能跑起来”的根基问题。就好比你要盖房子这层是地基地基不打平上面装修得再好也白搭。第二层是Python运行时环境。OpenClaw是基于Python的版本选择、虚拟环境、依赖管理都在这一层。python版本不对装什么包都可能失败。我用虚拟环境的目的很直接不让项目之间的依赖互相干扰。你不可能只跑一个OpenClaw以后还会装别的工具虚拟环境是最好用的隔离手段。第三层是项目依赖与配置。就是拉取OpenClaw仓库、安装它的Python依赖、设置初始配置文件。这一层最接近大家理解的“安装”但前面两层不做好这一层就会到处报错。这三个层面我会在后面的章节里依次展开每一层遇到什么问题、怎么排查我都会写清楚。这整个过程我并不把它当作单纯的安装流程而是当作一次对计算机环境的整体体检。3. 环境准备前的系统清点与工具链核查3.1 操作系统与硬件的最低门槛开始动手之前先确认你的电脑能不能跑得动OpenClaw。这里我不说那些复杂的官方配置表就说几个实际用过之后的硬标准。操作系统方面Windows、macOS、主流Linux发行版都可以。我自己主力机是Windows 11也在一台旧笔记本上跑过Ubuntu版本表现都不错。Windows上需要注意尽量用64位系统32位系统我劝你放弃吧现在很多Python包已经不支持32位了装到一半会直接报“not a supported wheel on this platform”。然后Windows版本不要太老最好Win10以上主要是OpenSSL等底层组件在新版本里才比较省心。内存8GB是底线16GB用起来比较舒服。OpenClaw本身占内存不算恐怖但它依赖的一些后台服务——比如消息接收进程、模型加载进程——加起来就上去了。我实测过在8GB内存的机器上只要同时不打开几十个浏览器标签页跑OpenClaw是没问题的但偶尔会有点喘。磁盘方面装完所有依赖加上项目本身大概需要2到3GB空间如果你容器镜像、模型缓存也要放在同一个盘建议留出至少10GB。CPU倒是没什么好担心的近十年的处理器都够用。真正吃资源的是后面跑模型推理的部分但那是使用阶段的事环境准备阶段不需要为它额外做什么。3.2 检查系统里是否已有需要的组件环境准备的第一步是先看看系统里已经有什么、缺什么。这一步是很多人跳过的我建议花两分钟做一遍能避免大量重复劳动。Windows系统打开PowerShell逐条输入下面几条命令python --version git --version where python如果python命令提示“无法识别”那就说明没装或者没加到环境变量里去。git同理。这两样是OpenClaw安装的硬前提缺哪个就先去装哪个。macOS和Linux也是一样的逻辑在终端里跑python3 --version git --version which python3这里有个容易踩的坑macOS系统自带的python3可能是旧版本有的甚至是2.7的残留。不要看它版本号是3.x就放心有些包依赖的特性它没有。我的建议是既然要走源码安装就统一装一个干净的新版Python不要依赖系统自带的后面创建虚拟环境时会省掉很多心智负担。除了Python和Git另外还有两个组件容易被忽略curl和ffmpeg。curl用来下载模型文件和远程资源ffmpeg用来处理音频。后面OpenClaw跑语音功能的时候没有ffmpeg就等着报错吧。Linux用户可以直接看能不能执行下面命令curl --version ffmpeg -version如果提示找不到可以用系统自带的包管理器装。Windows用户建议直接去官网下载安装包装完记得把安装目录加到Path里。3.3 网络环境的准备与镜像源切换OpenClaw安装过程中要拉取代码、下载依赖包这些操作都依赖网络。国内网络环境的特殊之处在于访问海外源比较慢而且时不时中断。我实际测试下来直接在默认源装依赖经常卡在一个包上半分钟不动最后超时失败。这不一定是你的网有问题就是源太远。解决办法很简单切换到国内镜像源。Python的pip可以永久配置镜像地址GitHub的代码拉取也可以用镜像加速地址替代。具体怎么配我放在后面安装依赖的那一节里写这里先提一句主要是想让你在正式动手前有这个心理准备——如果你发现网络卡不要怪自己是源的问题换掉就好。另外建议准备一个可靠的网络环境不要在那种信号忽强忽弱的公用WiFi下装。依赖包下载一旦中断pip的缓存机制有时会把半截文件缓存住下次重试一直报校验错误这时候还得清理缓存重来非常折腾。我第一次装的时候就吃过这个亏后来养成了习惯装大项目前先检查网络状况再开始操作。3.4 清理残留环境避免版本冲突最后一步准备是检查系统里有没有以前装过但没卸干净的Python、Node之类的东西。有些人电脑里会有两个Python版本一个是自己后来装的3.11另一个是某个软件捆绑的3.8。这种情况下你在命令行里敲python实际用的可能是旧的3.8而你需要的是3.11。我见过一个很典型的例子某同学命令行里python --version显示的是3.11他以为万事大吉结果pip install的时候却装到了3.8的环境里因为pip命令关联的是另一个Python进程。最后OpenClaw怎么都导入不了那个包查了半天才定位到是pip和python不是同一个版本。这里给一个实用小技巧在命令行运行where pythonWindows或which -a python3Linux/macOS会列出所有Python路径。如果你看到多个路径说明存在多版本并存的情况。这时候我建议不要想着去卸载旧的太冒险直接把新的Python路径在环境变量里提前让命令行优先找到它就行。后面创建虚拟环境时用绝对路径创建就完全可控了。4. 系统级依赖与编译工具链安装4.1 Windows系统的组件安装Visual C Build ToolsWindows上装OpenClaw你第一个要面对的不是Python而是Visual C Build Tools。这东西全名很长简单理解就是Windows平台的编译工具链。很多Python包不是纯Python写的它们混了C/C代码安装时需要现场编译。如果你的电脑上没装这套编译工具pip装到这类包时会直接报Microsoft Visual C 14.0 or greater is required然后安装失败。这个报错我见过无数次很多新手在这卡住不明白自己Linux、Mac上都好好的为什么Windows不行。原因就是Windows不会预装编译环境你必须手动装上。解决办法去Visual Studio官网下载Build Tools安装器。装的时候不要全选勾选“使用C的桌面开发”那个工作负载就行了里面包含了编译器和Windows SDK。这个安装包比较大有几个GB需要点耐心。装完重启一次终端一定要重启让环境变量生效。装好之后可以用下面的命令验证一下cl如果看到一段版本版权信息说明编译工具已就位。如果提示无法识别说明还没进环境变量可以去“编辑系统环境变量”里检查Path有没有包含Visual Studio Tools的相关路径。这一步搞定Windows的环境准备就成功了一半。4.2 macOS系统的组件安装Command Line Tools与HomebrewmacOS用户相对省心一点因为系统本身自带了一部分编译工具。你只需在终端执行xcode-select --install系统会弹窗提示安装Command Line Tools里面包含了git、clang编译器这些核心组件。装完之后git --version和cc --version都能用了。然后我强烈建议装一个Homebrew。它和apt是类似的东西但更适合macOS。后面你要装ffmpeg、装各种系统库通过Homebrew一条命令就搞定了。安装方法/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)装的过程可能比较久国内网络环境下容易卡在下载更新那一步建议配置一下国内镜像源再执行。装完跑brew --version验证通过后可以先帮你装个ffmpegbrew install ffmpeg这一步不是必须马上做但建议提前装了后面不会因为缺这个再折腾。4.3 Linux系统的组件安装以Debian系为例Linux环境是OpenClaw跑得最顺畅的平台组件安装也最简单用包管理器一条命令搞定。以Ubuntu/Debian系为例sudo apt update sudo apt install -y build-essential git curl ffmpeg libssl-dev zlib1g-dev这里的build-essential包含了gcc、g、make等编译工具libssl-dev和zlib1g-dev是很多Python包编译时的依赖库。如果缺了它们装某些包时会报openssl/ssl.h: No such file or directory这种头文件缺失的问题最难搞所以提前装上省心。如果你用的是CentOS/RHEL系命令会有点不同用dnf或yum装对应的包就行思路完全一致编译工具链、git、curl、ffmpeg、openssl-devel一个都不能少。我接触过的很多踩坑案例最后查来查去都指向同一个毛病少了编译工具链pip尝试源码编译某个包时直接失败。这个问题的坑在于报错信息有时候非常隐蔽不直接说“编译失败”而是说“找不到某个文件”新手根本联系不到是缺编译器。所以这一节我怎么强调都不为过先装编译工具链再往下走。4.4 目录规划与权限处理环境准备阶段还有一个常常被忽略的问题装在哪里。很多人习惯直接在系统盘的用户目录下装这也没毛病但要注意路径里别有中文和空格。某些Python包在处理带空格的路径时会出问题尤其是Windows系统反斜杠加空格组合容易让路径解析出错。我的建议是刻意建一个干净的目录。比如在Windows的D盘根目录下建F:\Tools在Linux下可以建~/workspace之类的目录然后把OpenClaw相关的项目都放在里面。路径越短越好越纯英文越好。这样做的收益是长远的以后配置环境变量、写脚本时路径短一点出错概率低很多。还有权限问题。Linux和macOS下不要用root身份去装Python包。我之前就因为省事直接sudo pip install XXXX结果包装到了系统目录和系统自带的Python混在一起后来系统升级的时候全部崩掉。正确做法是用普通用户身份创建虚拟环境所有操作都在虚拟环境和项目目录里进行完全不触碰系统级Python目录。5. Python运行时安装与虚拟环境配置5.1 选择哪个Python版本OpenClaw对Python版本的要求我用下来感觉3.10、3.11、3.12都能跑但最省心的还是3.11。为什么这么说3.10时代有些依赖还不兼容最新语法3.12出的那阵子很多第三方包还没来得及适配元数据声明跟不上pip安装时会提示版本不受支持。等到3.12稳定下来兼容性已经好些了但如果你不是需要特别新特性的场景3.11就是最稳妥的选择。去Python官网下载安装包时要注意Windows安装器里有一个很关键的勾选项“Add Python to PATH”。很多新手不看这一项默认不勾装完python命令用不了。我的建议是一定勾上虽然网上有些人说这样会和已有版本冲突但实际上只要你后续用虚拟环境管理PATH里有Python是好事能省不少事。Linux用户我建议用源码编译安装Python或者用官方提供的部署工具。Ubuntu下用apt直接装python3.11也能用没什么大问题。重点就一个确认你命令行里的python3 --version和pip3 --version指向的是同一个版本。不同步的话下面创建虚拟环境时会很混乱。5.2 创建虚拟环境并激活虚拟环境这东西我每次讲都像在劝人出门戴口罩——大家都知道重要但总有人偷懒。你不希望OpenClaw的依赖和你系统里其他项目的依赖互相踩脚的话就用它。在项目目录里执行python -m venv openclaw_env这个命令会创建一个叫openclaw_env的目录里面包含了一个独立的Python副本。激活它Windows PowerShell下.\openclaw_env\Scripts\Activate.ps1如果提示“因为在此系统上禁止运行脚本”需要先用管理员权限执行Set-ExecutionPolicy RemoteSigned放开脚本运行限制。Linux/macOS下source openclaw_env/bin/activate激活之后命令行提示符前会出现(openclaw_env)字样。看到这个说明你已经在这个独立的Python环境里了。之后所有pip安装都只会装到这个环境的目录里和系统其他位置完全隔离。这是整个环境准备环节中我认为最重要的一步没有之一。5.3 配置pip镜像源与基础包激活虚拟环境后第一件事是配置pip镜像源。我用的镜像配置写入~/.pip/pip.confLinux/macOS或C:\Users\你的用户名\AppData\Roaming\pip\pip.iniWindows[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn配好后测试一下pip config list pip install --upgrade pip升级pip的时候会看到下载速度明显起来了。这一步看似小实际作用非常大。默认源下载速度可以慢到你怀疑人生而切换镜像后几十MB的包十几秒就下完。如果你用的是教育网还可以考虑用对应学校的源速度可能会更快。基础包我在这个阶段一般会先装上wheel和setuptools。这两个不是为了OpenClaw直接用的而是为了后续编译类包装起来更顺。很多包在安装时要先跑构建脚本这两个工具就是为构建过程服务的。6. 拉取OpenClaw源码与核心依赖安装6.1 从GitHub拉取项目仓库环境准备好了开始拉代码。这一步唯一要注意的是仓库地址别搞错。用Git克隆git clone https://github.com/你的仓库地址/openclaw.git克隆完成后进入项目目录cd openclaw如果你所在网络访问GitHub速度不稳可以尝试把https地址替换为镜像加速地址比如常见的镜像前缀https://ghproxy.com/https://github.com/...。这个方案不是100%稳定因为镜像服务本身可能有变动但应急是够用的。第一次克隆失败不用慌删掉失败的目录重新来一次或者网络好的时候再试。拉下来之后先看一眼目录结构。主要关注requirements.txt文件和项目的README文档。README里通常会写当前版本依赖的环境要求我建议你花几分钟读一下可能比我这篇教程的通用步骤更贴合当时的版本。6.2 安装核心Python依赖依赖安装是整个OpenClaw安装过程中最考验耐心的一步。在虚拟环境激活状态下执行pip install -r requirements.txt这个过程会下载几十个包。不同电脑情况不一样顺利的话十分钟左右慢的话可能半小时。等了这么久你必须盯一下安装过程的输出不要让它自己跑完就撒手不管。主要看两类信息。一类是ERROR和Failed这类直接说明某个包装不上。另一类是Building wheel如果某个包开始编译源码了说明它没有现成的二进制包需要现场构建这一步如果失败原因基本就是缺编译工具链回头检查上一章的系统组件装没装好。安装结束后验证一下关键依赖pip list看一下核心的依赖包是否都出现在列表里并且版本号合理。如果发现某个包没有单独装一次pip install 包名如果是网络原因导致失败的重试时可以把超时时间调大pip install --timeout 60 -r requirements.txt遇到error: subprocess-exited-with-error这类报错一般有两个方向一个是编译工具链的问题另一个是Python版本问题。先用python --version确认版本再检查gcc/Visual Studio工具是否安装逐个排除。我前面之所以反复强调环境准备的重要性就是因为几乎所有这类报错都追溯到这几个根因上。6.3 初始化配置文件的准备依赖装完了但项目还差一个配置文件。OpenClaw启动时会读取一个配置里面包含模型接口参数、运行模式、账号信息等。新克隆的仓库通常不直接带可用的配置文件模板你需要自己创建。在项目根目录下一般有一个config.example.yaml或类似文件把它复制一份命名为实际读取的名字cp config.example.yaml config.yaml然后打开config.yaml按照注释逐项填写。先把必要的几个核心项填好次要的项等后面实际使用时再继续调整。我建议第一次运行时配置从简不要试图把每一个开关都搞清楚先让整个系统能转起来再逐个功能优化。注意配置文件里的密钥信息要妥善保管。不要在社区、贴吧这些公开场合发自己完整的配置内容尤其是含账号密钥的部分。我见过有人把配置截屏发出来被提醒这个事说大不大说小不小养成好习惯总是没错的。7. 安装验证与常见问题排查7.1 三步验证低频快速确认安装成功装完之后不要急着去跑完整功能先做三个基础验证确保环境是健康的。第一步验证Python环境是一致的python --version which python确保你当前在虚拟环境里并且Python版本符合OpenClaw要求。第二步验证核心依赖安装成功。很多时候依赖装完后因为某个环节出了问题实际导入时会报错。跑一个快速导入测试python -c import openclaw; print(openclaw.__version__)如果这条命令没有报错说明OpenClaw的主包已经可以被Python导入了这是一个非常关键的信号。出现ModuleNotFoundError的话说明依赖缺失或者包的安装路径有问题。第三步执行一个项目自带的自检脚本。不少项目会有--check之类的参数。如果OpenClaw提供了类似工具运行它会输出当前环境的体检结果一眼看出还有什么缺失项。以我经验这个自检工具通常能直接告诉你缺哪个库、哪个配置不对是排查问题的最佳入口。以上三步都通过恭喜你环境准备这一步算真正完成了。7.2 常见问题速查表我把环境准备阶段见过的高频问题整理成了表格方便你对照排查报错现象根本原因解决方案Microsoft Visual C 14.0 or greater is requiredWindows缺编译工具链安装Visual Studio Build Tools勾选C桌面开发python: command not foundPython未加入PATH到环境变量里添加Python安装路径并重开终端ModuleNotFoundError: No module named xxx依赖未安装或安装不完整在虚拟环境中执行pip install -r requirements.txtpip install 超时/中断网络连接默认源不稳定切换国内镜像源并设置--timeout 60error: subprocess-exited-with-error编译工具或头文件缺失确认系统级编译工具已安装检查Python版本安装时报No matching distribution foundPython版本过新/过旧切换Python到3.11或3.12激活虚拟环境报脚本禁止运行Windows脚本策略限制以管理员运行Set-ExecutionPolicy RemoteSigned这张表覆盖了七八成的新手问题。如果遇到表中没有的现象我的建议是优先去查项目的Issue区一般都会有人遇到过相同或类似的情况在讨论记录里往往能翻到解决方案。7.3 我踩过的一些坑最后分享几个我实际遇到过的、比较冷门的坑。第一个是Windows终端和Windows PowerShell的差异。同样的命令在cmd下和PowerShell下行为不一致尤其是激活虚拟环境的命令。第一次用的时候用cmd执行了PowerShell的激活语句提示找不到命令我一度以为环境坏了。其实只是语法差异用对命令就好。第二个是某次我为了省事直接用系统Python全局安装OpenClaw没建虚拟环境。过了段时间系统里另一个工具自动升级了一个共享依赖库的版本OpenClaw直接罢工。虚拟环境这个习惯真的是被教训出来的。第三个是路径里的空格问题。有一次我把项目放在D:\My Programs\openclaw这样的路径下配置文件里引用资源的相对路径没问题但某些底层库解析绝对路径时出现空格转义问题报错信息极其抽象排查了很久。后来我把项目移到纯英文无空格路径下问题消失了。自那以后我对安装路径的要求就两个字干净。7.4 一份合格的环境准备检查清单最后给你一份我自己用的检查清单做完一项勾一项全部完成以后再去启动OpenClaw操作系统与硬件满足要求必要的系统级编译工具已安装Git与curl可用Python版本正确且建议使用虚拟环境虚拟环境创建并激活成功pip镜像源已配置基础包可用OpenClaw仓库拉取成功依赖安装完成无报错OpenClaw可正常导入无ModuleNotFoundError配置文件已创建并填写必要项我自己的做法是每换一台电脑部署都会从这份清单走一遍。老实讲直到现在我偶尔也会在某个环节犯低级错误但因为有这份清单在每次都能很快定位问题不至于一头扎进去无法自拔。环境准备这件事说白了就是“把地基打牢”。地基稳了后面OpenClaw的安装和使用就都顺理成章。如果你按这篇教程完整走通了OpenClaw之后的功能配置、模式调优那些都是可以用时间慢慢打磨的事而不会让环境问题成为卡住你的那只手。 
长河君 · 2026/10/20 22:02:02 · 阅读 1.2k OpenClaw环境准备全攻略：从系统工具链到Python虚拟环境
2. 环境准备方案的整体设计与选型思路2.1 为什么环境准备是OpenClaw安装的“第一道坎”很多朋友拿到OpenClaw第一反应是直接git clone然后pip install结果装到一半被各种报错劝退。我见过太多次这样的场景代码拉下来了依赖装了十分钟最后卡在一个libffi或者OpenSSL的版本问题上怎么折腾都过不去最后只能重装系统。其实问题根本不在你的操作而在环境准备这一步没做到位。OpenClaw这类工具和其他普通Python项目有个本质区别它对底层系统环境的要求比一般应用高不少。它不只是跑一段逻辑代码而是要调用本机的各种能力接口——比如音频解码、图像处理、消息推送还要和系统的Shell交互。这些能力不是pip装个包就能解决的它们依赖的是一些C语言编译的动态库、系统的底层组件。如果环境准备这一步没有把这些底子打好后面装什么都会磕磕绊绊。我自己的习惯是拿到一个新项目先不急着装花二十分钟把环境梳理一遍。这二十分钟花得非常值它能帮你避免之后两三个小时的排错时间。而且环境准备好一次之后不仅OpenClaw能用以后装别的同类型项目都会顺利很多。2.2 三种部署方式为什么推荐源码安装OpenClaw的常见部署方式有几种直接下载发行版压缩包、用包管理器安装、从源码安装。我自己试过前两种后来一直用的是源码安装原因很简单——发行版也好、镜像包也好它们都封装好了方便是方便但一旦你想改配置、换模型接口、加自定义插件就会觉得束手束脚。用包管理器安装的问题在于很多依赖版本被固定住了看起来装完了实际上某些子依赖的版本是旧版和当前系统不完全匹配。你运行OpenClaw的时候它不会立刻报错但是跑到某个具体功能时会突然崩溃这种问题是最难排查的。源码安装反而是最稳的一条路。它看起来步骤多一点但实际上每一步都可以控制出了问题你能定位到具体环节。环境准备的核心思路就是为这种可控性服务的先把系统工具链配好再把Python环境隔离好最后拉代码装依赖。每一层都清清楚楚出了问题你知道去哪查。我推荐有动手能力的朋友都走源码安装这条路。如果你是第一次接触这块也不用慌接下来我拆开一步一步讲跟着做就行。2.3 环境准备的核心思路三个层面一次搞定我把整个环境准备拆成三个层面这个思路在解决同类问题时也通用。第一层是系统级环境。包括操作系统的基础组件、编译工具链、需要用到的系统库。这一层解决的是“OpenClaw能不能跑起来”的根基问题。就好比你要盖房子这层是地基地基不打平上面装修得再好也白搭。第二层是Python运行时环境。OpenClaw是基于Python的版本选择、虚拟环境、依赖管理都在这一层。python版本不对装什么包都可能失败。我用虚拟环境的目的很直接不让项目之间的依赖互相干扰。你不可能只跑一个OpenClaw以后还会装别的工具虚拟环境是最好用的隔离手段。第三层是项目依赖与配置。就是拉取OpenClaw仓库、安装它的Python依赖、设置初始配置文件。这一层最接近大家理解的“安装”但前面两层不做好这一层就会到处报错。这三个层面我会在后面的章节里依次展开每一层遇到什么问题、怎么排查我都会写清楚。这整个过程我并不把它当作单纯的安装流程而是当作一次对计算机环境的整体体检。3. 环境准备前的系统清点与工具链核查3.1 操作系统与硬件的最低门槛开始动手之前先确认你的电脑能不能跑得动OpenClaw。这里我不说那些复杂的官方配置表就说几个实际用过之后的硬标准。操作系统方面Windows、macOS、主流Linux发行版都可以。我自己主力机是Windows 11也在一台旧笔记本上跑过Ubuntu版本表现都不错。Windows上需要注意尽量用64位系统32位系统我劝你放弃吧现在很多Python包已经不支持32位了装到一半会直接报“not a supported wheel on this platform”。然后Windows版本不要太老最好Win10以上主要是OpenSSL等底层组件在新版本里才比较省心。内存8GB是底线16GB用起来比较舒服。OpenClaw本身占内存不算恐怖但它依赖的一些后台服务——比如消息接收进程、模型加载进程——加起来就上去了。我实测过在8GB内存的机器上只要同时不打开几十个浏览器标签页跑OpenClaw是没问题的但偶尔会有点喘。磁盘方面装完所有依赖加上项目本身大概需要2到3GB空间如果你容器镜像、模型缓存也要放在同一个盘建议留出至少10GB。CPU倒是没什么好担心的近十年的处理器都够用。真正吃资源的是后面跑模型推理的部分但那是使用阶段的事环境准备阶段不需要为它额外做什么。3.2 检查系统里是否已有需要的组件环境准备的第一步是先看看系统里已经有什么、缺什么。这一步是很多人跳过的我建议花两分钟做一遍能避免大量重复劳动。Windows系统打开PowerShell逐条输入下面几条命令python --version git --version where python如果python命令提示“无法识别”那就说明没装或者没加到环境变量里去。git同理。这两样是OpenClaw安装的硬前提缺哪个就先去装哪个。macOS和Linux也是一样的逻辑在终端里跑python3 --version git --version which python3这里有个容易踩的坑macOS系统自带的python3可能是旧版本有的甚至是2.7的残留。不要看它版本号是3.x就放心有些包依赖的特性它没有。我的建议是既然要走源码安装就统一装一个干净的新版Python不要依赖系统自带的后面创建虚拟环境时会省掉很多心智负担。除了Python和Git另外还有两个组件容易被忽略curl和ffmpeg。curl用来下载模型文件和远程资源ffmpeg用来处理音频。后面OpenClaw跑语音功能的时候没有ffmpeg就等着报错吧。Linux用户可以直接看能不能执行下面命令curl --version ffmpeg -version如果提示找不到可以用系统自带的包管理器装。Windows用户建议直接去官网下载安装包装完记得把安装目录加到Path里。3.3 网络环境的准备与镜像源切换OpenClaw安装过程中要拉取代码、下载依赖包这些操作都依赖网络。国内网络环境的特殊之处在于访问海外源比较慢而且时不时中断。我实际测试下来直接在默认源装依赖经常卡在一个包上半分钟不动最后超时失败。这不一定是你的网有问题就是源太远。解决办法很简单切换到国内镜像源。Python的pip可以永久配置镜像地址GitHub的代码拉取也可以用镜像加速地址替代。具体怎么配我放在后面安装依赖的那一节里写这里先提一句主要是想让你在正式动手前有这个心理准备——如果你发现网络卡不要怪自己是源的问题换掉就好。另外建议准备一个可靠的网络环境不要在那种信号忽强忽弱的公用WiFi下装。依赖包下载一旦中断pip的缓存机制有时会把半截文件缓存住下次重试一直报校验错误这时候还得清理缓存重来非常折腾。我第一次装的时候就吃过这个亏后来养成了习惯装大项目前先检查网络状况再开始操作。3.4 清理残留环境避免版本冲突最后一步准备是检查系统里有没有以前装过但没卸干净的Python、Node之类的东西。有些人电脑里会有两个Python版本一个是自己后来装的3.11另一个是某个软件捆绑的3.8。这种情况下你在命令行里敲python实际用的可能是旧的3.8而你需要的是3.11。我见过一个很典型的例子某同学命令行里python --version显示的是3.11他以为万事大吉结果pip install的时候却装到了3.8的环境里因为pip命令关联的是另一个Python进程。最后OpenClaw怎么都导入不了那个包查了半天才定位到是pip和python不是同一个版本。这里给一个实用小技巧在命令行运行where pythonWindows或which -a python3Linux/macOS会列出所有Python路径。如果你看到多个路径说明存在多版本并存的情况。这时候我建议不要想着去卸载旧的太冒险直接把新的Python路径在环境变量里提前让命令行优先找到它就行。后面创建虚拟环境时用绝对路径创建就完全可控了。4. 系统级依赖与编译工具链安装4.1 Windows系统的组件安装Visual C Build ToolsWindows上装OpenClaw你第一个要面对的不是Python而是Visual C Build Tools。这东西全名很长简单理解就是Windows平台的编译工具链。很多Python包不是纯Python写的它们混了C/C代码安装时需要现场编译。如果你的电脑上没装这套编译工具pip装到这类包时会直接报Microsoft Visual C 14.0 or greater is required然后安装失败。这个报错我见过无数次很多新手在这卡住不明白自己Linux、Mac上都好好的为什么Windows不行。原因就是Windows不会预装编译环境你必须手动装上。解决办法去Visual Studio官网下载Build Tools安装器。装的时候不要全选勾选“使用C的桌面开发”那个工作负载就行了里面包含了编译器和Windows SDK。这个安装包比较大有几个GB需要点耐心。装完重启一次终端一定要重启让环境变量生效。装好之后可以用下面的命令验证一下cl如果看到一段版本版权信息说明编译工具已就位。如果提示无法识别说明还没进环境变量可以去“编辑系统环境变量”里检查Path有没有包含Visual Studio Tools的相关路径。这一步搞定Windows的环境准备就成功了一半。4.2 macOS系统的组件安装Command Line Tools与HomebrewmacOS用户相对省心一点因为系统本身自带了一部分编译工具。你只需在终端执行xcode-select --install系统会弹窗提示安装Command Line Tools里面包含了git、clang编译器这些核心组件。装完之后git --version和cc --version都能用了。然后我强烈建议装一个Homebrew。它和apt是类似的东西但更适合macOS。后面你要装ffmpeg、装各种系统库通过Homebrew一条命令就搞定了。安装方法/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)装的过程可能比较久国内网络环境下容易卡在下载更新那一步建议配置一下国内镜像源再执行。装完跑brew --version验证通过后可以先帮你装个ffmpegbrew install ffmpeg这一步不是必须马上做但建议提前装了后面不会因为缺这个再折腾。4.3 Linux系统的组件安装以Debian系为例Linux环境是OpenClaw跑得最顺畅的平台组件安装也最简单用包管理器一条命令搞定。以Ubuntu/Debian系为例sudo apt update sudo apt install -y build-essential git curl ffmpeg libssl-dev zlib1g-dev这里的build-essential包含了gcc、g、make等编译工具libssl-dev和zlib1g-dev是很多Python包编译时的依赖库。如果缺了它们装某些包时会报openssl/ssl.h: No such file or directory这种头文件缺失的问题最难搞所以提前装上省心。如果你用的是CentOS/RHEL系命令会有点不同用dnf或yum装对应的包就行思路完全一致编译工具链、git、curl、ffmpeg、openssl-devel一个都不能少。我接触过的很多踩坑案例最后查来查去都指向同一个毛病少了编译工具链pip尝试源码编译某个包时直接失败。这个问题的坑在于报错信息有时候非常隐蔽不直接说“编译失败”而是说“找不到某个文件”新手根本联系不到是缺编译器。所以这一节我怎么强调都不为过先装编译工具链再往下走。4.4 目录规划与权限处理环境准备阶段还有一个常常被忽略的问题装在哪里。很多人习惯直接在系统盘的用户目录下装这也没毛病但要注意路径里别有中文和空格。某些Python包在处理带空格的路径时会出问题尤其是Windows系统反斜杠加空格组合容易让路径解析出错。我的建议是刻意建一个干净的目录。比如在Windows的D盘根目录下建F:\Tools在Linux下可以建~/workspace之类的目录然后把OpenClaw相关的项目都放在里面。路径越短越好越纯英文越好。这样做的收益是长远的以后配置环境变量、写脚本时路径短一点出错概率低很多。还有权限问题。Linux和macOS下不要用root身份去装Python包。我之前就因为省事直接sudo pip install XXXX结果包装到了系统目录和系统自带的Python混在一起后来系统升级的时候全部崩掉。正确做法是用普通用户身份创建虚拟环境所有操作都在虚拟环境和项目目录里进行完全不触碰系统级Python目录。5. Python运行时安装与虚拟环境配置5.1 选择哪个Python版本OpenClaw对Python版本的要求我用下来感觉3.10、3.11、3.12都能跑但最省心的还是3.11。为什么这么说3.10时代有些依赖还不兼容最新语法3.12出的那阵子很多第三方包还没来得及适配元数据声明跟不上pip安装时会提示版本不受支持。等到3.12稳定下来兼容性已经好些了但如果你不是需要特别新特性的场景3.11就是最稳妥的选择。去Python官网下载安装包时要注意Windows安装器里有一个很关键的勾选项“Add Python to PATH”。很多新手不看这一项默认不勾装完python命令用不了。我的建议是一定勾上虽然网上有些人说这样会和已有版本冲突但实际上只要你后续用虚拟环境管理PATH里有Python是好事能省不少事。Linux用户我建议用源码编译安装Python或者用官方提供的部署工具。Ubuntu下用apt直接装python3.11也能用没什么大问题。重点就一个确认你命令行里的python3 --version和pip3 --version指向的是同一个版本。不同步的话下面创建虚拟环境时会很混乱。5.2 创建虚拟环境并激活虚拟环境这东西我每次讲都像在劝人出门戴口罩——大家都知道重要但总有人偷懒。你不希望OpenClaw的依赖和你系统里其他项目的依赖互相踩脚的话就用它。在项目目录里执行python -m venv openclaw_env这个命令会创建一个叫openclaw_env的目录里面包含了一个独立的Python副本。激活它Windows PowerShell下.\openclaw_env\Scripts\Activate.ps1如果提示“因为在此系统上禁止运行脚本”需要先用管理员权限执行Set-ExecutionPolicy RemoteSigned放开脚本运行限制。Linux/macOS下source openclaw_env/bin/activate激活之后命令行提示符前会出现(openclaw_env)字样。看到这个说明你已经在这个独立的Python环境里了。之后所有pip安装都只会装到这个环境的目录里和系统其他位置完全隔离。这是整个环境准备环节中我认为最重要的一步没有之一。5.3 配置pip镜像源与基础包激活虚拟环境后第一件事是配置pip镜像源。我用的镜像配置写入~/.pip/pip.confLinux/macOS或C:\Users\你的用户名\AppData\Roaming\pip\pip.iniWindows[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn配好后测试一下pip config list pip install --upgrade pip升级pip的时候会看到下载速度明显起来了。这一步看似小实际作用非常大。默认源下载速度可以慢到你怀疑人生而切换镜像后几十MB的包十几秒就下完。如果你用的是教育网还可以考虑用对应学校的源速度可能会更快。基础包我在这个阶段一般会先装上wheel和setuptools。这两个不是为了OpenClaw直接用的而是为了后续编译类包装起来更顺。很多包在安装时要先跑构建脚本这两个工具就是为构建过程服务的。6. 拉取OpenClaw源码与核心依赖安装6.1 从GitHub拉取项目仓库环境准备好了开始拉代码。这一步唯一要注意的是仓库地址别搞错。用Git克隆git clone https://github.com/你的仓库地址/openclaw.git克隆完成后进入项目目录cd openclaw如果你所在网络访问GitHub速度不稳可以尝试把https地址替换为镜像加速地址比如常见的镜像前缀https://ghproxy.com/https://github.com/...。这个方案不是100%稳定因为镜像服务本身可能有变动但应急是够用的。第一次克隆失败不用慌删掉失败的目录重新来一次或者网络好的时候再试。拉下来之后先看一眼目录结构。主要关注requirements.txt文件和项目的README文档。README里通常会写当前版本依赖的环境要求我建议你花几分钟读一下可能比我这篇教程的通用步骤更贴合当时的版本。6.2 安装核心Python依赖依赖安装是整个OpenClaw安装过程中最考验耐心的一步。在虚拟环境激活状态下执行pip install -r requirements.txt这个过程会下载几十个包。不同电脑情况不一样顺利的话十分钟左右慢的话可能半小时。等了这么久你必须盯一下安装过程的输出不要让它自己跑完就撒手不管。主要看两类信息。一类是ERROR和Failed这类直接说明某个包装不上。另一类是Building wheel如果某个包开始编译源码了说明它没有现成的二进制包需要现场构建这一步如果失败原因基本就是缺编译工具链回头检查上一章的系统组件装没装好。安装结束后验证一下关键依赖pip list看一下核心的依赖包是否都出现在列表里并且版本号合理。如果发现某个包没有单独装一次pip install 包名如果是网络原因导致失败的重试时可以把超时时间调大pip install --timeout 60 -r requirements.txt遇到error: subprocess-exited-with-error这类报错一般有两个方向一个是编译工具链的问题另一个是Python版本问题。先用python --version确认版本再检查gcc/Visual Studio工具是否安装逐个排除。我前面之所以反复强调环境准备的重要性就是因为几乎所有这类报错都追溯到这几个根因上。6.3 初始化配置文件的准备依赖装完了但项目还差一个配置文件。OpenClaw启动时会读取一个配置里面包含模型接口参数、运行模式、账号信息等。新克隆的仓库通常不直接带可用的配置文件模板你需要自己创建。在项目根目录下一般有一个config.example.yaml或类似文件把它复制一份命名为实际读取的名字cp config.example.yaml config.yaml然后打开config.yaml按照注释逐项填写。先把必要的几个核心项填好次要的项等后面实际使用时再继续调整。我建议第一次运行时配置从简不要试图把每一个开关都搞清楚先让整个系统能转起来再逐个功能优化。注意配置文件里的密钥信息要妥善保管。不要在社区、贴吧这些公开场合发自己完整的配置内容尤其是含账号密钥的部分。我见过有人把配置截屏发出来被提醒这个事说大不大说小不小养成好习惯总是没错的。7. 安装验证与常见问题排查7.1 三步验证低频快速确认安装成功装完之后不要急着去跑完整功能先做三个基础验证确保环境是健康的。第一步验证Python环境是一致的python --version which python确保你当前在虚拟环境里并且Python版本符合OpenClaw要求。第二步验证核心依赖安装成功。很多时候依赖装完后因为某个环节出了问题实际导入时会报错。跑一个快速导入测试python -c import openclaw; print(openclaw.__version__)如果这条命令没有报错说明OpenClaw的主包已经可以被Python导入了这是一个非常关键的信号。出现ModuleNotFoundError的话说明依赖缺失或者包的安装路径有问题。第三步执行一个项目自带的自检脚本。不少项目会有--check之类的参数。如果OpenClaw提供了类似工具运行它会输出当前环境的体检结果一眼看出还有什么缺失项。以我经验这个自检工具通常能直接告诉你缺哪个库、哪个配置不对是排查问题的最佳入口。以上三步都通过恭喜你环境准备这一步算真正完成了。7.2 常见问题速查表我把环境准备阶段见过的高频问题整理成了表格方便你对照排查报错现象根本原因解决方案Microsoft Visual C 14.0 or greater is requiredWindows缺编译工具链安装Visual Studio Build Tools勾选C桌面开发python: command not foundPython未加入PATH到环境变量里添加Python安装路径并重开终端ModuleNotFoundError: No module named xxx依赖未安装或安装不完整在虚拟环境中执行pip install -r requirements.txtpip install 超时/中断网络连接默认源不稳定切换国内镜像源并设置--timeout 60error: subprocess-exited-with-error编译工具或头文件缺失确认系统级编译工具已安装检查Python版本安装时报No matching distribution foundPython版本过新/过旧切换Python到3.11或3.12激活虚拟环境报脚本禁止运行Windows脚本策略限制以管理员运行Set-ExecutionPolicy RemoteSigned这张表覆盖了七八成的新手问题。如果遇到表中没有的现象我的建议是优先去查项目的Issue区一般都会有人遇到过相同或类似的情况在讨论记录里往往能翻到解决方案。7.3 我踩过的一些坑最后分享几个我实际遇到过的、比较冷门的坑。第一个是Windows终端和Windows PowerShell的差异。同样的命令在cmd下和PowerShell下行为不一致尤其是激活虚拟环境的命令。第一次用的时候用cmd执行了PowerShell的激活语句提示找不到命令我一度以为环境坏了。其实只是语法差异用对命令就好。第二个是某次我为了省事直接用系统Python全局安装OpenClaw没建虚拟环境。过了段时间系统里另一个工具自动升级了一个共享依赖库的版本OpenClaw直接罢工。虚拟环境这个习惯真的是被教训出来的。第三个是路径里的空格问题。有一次我把项目放在D:\My Programs\openclaw这样的路径下配置文件里引用资源的相对路径没问题但某些底层库解析绝对路径时出现空格转义问题报错信息极其抽象排查了很久。后来我把项目移到纯英文无空格路径下问题消失了。自那以后我对安装路径的要求就两个字干净。7.4 一份合格的环境准备检查清单最后给你一份我自己用的检查清单做完一项勾一项全部完成以后再去启动OpenClaw操作系统与硬件满足要求必要的系统级编译工具已安装Git与curl可用Python版本正确且建议使用虚拟环境虚拟环境创建并激活成功pip镜像源已配置基础包可用OpenClaw仓库拉取成功依赖安装完成无报错OpenClaw可正常导入无ModuleNotFoundError配置文件已创建并填写必要项我自己的做法是每换一台电脑部署都会从这份清单走一遍。老实讲直到现在我偶尔也会在某个环节犯低级错误但因为有这份清单在每次都能很快定位问题不至于一头扎进去无法自拔。环境准备这件事说白了就是“把地基打牢”。地基稳了后面OpenClaw的安装和使用就都顺理成章。如果你按这篇教程完整走通了OpenClaw之后的功能配置、模式调优那些都是可以用时间慢慢打磨的事而不会让环境问题成为卡住你的那只手。