前阵子有位朋友在群里发消息说自己照着 OpenClaw 的 README 装三步就卡住了。不是网络问题不是电脑太老就是卡在终端里报了一个不算复杂的错误。我说你把报错发来看看结果发现是连最基本的路径和权限概念都没理顺。这其实不是个例——OpenClaw 这个开源个人智能助手框架名字听起来很酷安装门槛也不算高但对完全没接触过命令行的零基础用户来说Windows 和 macOS 两条路上都有不少隐藏的小坑。这篇文章就是给你这种听说过、想试试、但没系统玩过命令行的人准备的。OpenClaw 是什么这里不多展开你只需要知道它是一个能对接多种本地模型和工具、帮你自动化处理日常任务的个人助理框架。装好之后你可以通过对话让它查资料、生成内容、调用各类脚本。下面我会把 Windows 和 macOS 两条部署路径拆开来讲每一步都说明为什么要这么做、报错出现时怎么判断以及哪些是安装前必须补上的基础技能。整篇内容我尽量用一个过来人带你操作的口吻不堆术语但涉及关键概念时会给足解释保证小白能照着走完有点基础的人也能从中避掉几个我当年踩过的坑。1. 部署前的三样必要技能为什么零基础不等于零准备1.1 终端到底是个什么东西很多教程开篇就说打开终端执行以下命令但没人告诉你终端是什么、为什么非要跟它打交道。如果你之前只用过手机 App 或电脑桌面的图形界面那我建议先花十分钟把终端这个概念搞明白。终端Terminal本质上就是一个让你用文字给电脑下指令的窗口。你在图形界面里点鼠标能做的事终端里用一行命令也同样能做甚至能做更多。Windows 上叫 PowerShell 或命令提示符macOS 上叫终端Terminal.app。OpenClaw 的安装过程之所以离不开终端是因为它本质是一个命令行工具——它的安装脚本、配置文件、启动方式都是围绕终端设计的你不可能绕过它。我见过不少新人一看到黑底白字的窗口就发怵其实完全没必要。你只需要掌握三件事第一命令分输入和回车确认两步第二命令窗口里的文字不会弄坏电脑最多报个错第三大部分错误提示都有规律复制到搜索引擎里就能找到答案。抱着这个心态终端就是你的工具箱不是老虎。1.2 必补基础之一路径和目录的底层逻辑安装 OpenClaw 时你会频繁和路径打交道。什么是路径就是电脑上某个文件或文件夹的门牌地址。Windows 的路径长这样C:\Users\你的用户名\DownloadsmacOS 长这样/Users/你的用户名/Downloads。两者一个用反斜杠\一个用正斜杠/这是很多命令在双平台表现不一致的根源。在终端里你必须知道两件事当前在哪要去哪。输入pwdPrint Working Directory可以显示当前所在目录输入lsmacOS/Linux或dirWindows可以查看当前目录下有什么。安装 OpenClaw 时官方给你的命令默认是在用户主目录下执行的如果在别的目录执行导致找不到文件八成就是路径问题。还有一个与路径有关的坑尽量选择纯英文路径安装。如果你的 Windows 用户名是中文比如C:\Users\张三某些开源工具对中文路径支持并不完美会在莫名其妙的地方报编码错误。解决办法是装到一个纯英文路径下比如D:\tools\openclaw。这不算歧视中文纯粹是历史兼容性原因能避开就避开。1.3 必补基础之二包管理器是应用商店的命令行版本你在手机上下 App 是不是都走应用商店电脑上的包管理器也是类似的东西。Windows 上的winget、macOS 上的Homebrew常简称 brew还有编程语言级别的pipPython 的包管理器都是命令行版应用商店。OpenClaw 依赖 Python、Git、Node.js 等一堆运行环境你当然可以去官网一个个下载安装包然后用鼠标点下一步但那样既慢又容易漏。更专业的做法是先安装包管理器再用几行命令把这些依赖统一装好。包管理器的好处是能自动处理依赖关系——比如某个工具需要特定版本的另一个库包管理器会帮你自动装好而不需要你手动去找。你可能想问那我能不能完全不学包管理器全用安装包可以但操作量会翻倍而且后续 OpenClaw 更新时用包管理器只需要一条命令手动安装却要重新下载覆盖非常麻烦。所以既然要零基础部署不如从一开始就走专业路线。1.4 必补基础之三读懂报错比背命令更重要零基础用户最常犯的一个错误是以为命令执行之后就万事大吉。实际上终端里执行完命令屏幕上会返回一堆信息。这些信息至少分为两类正常的输出和错误提示。错误提示通常以Error、Traceback、fatal、command not found等关键词开头。你需要培养的能力是报错出现时不要慌不要立刻关掉窗口先把报错内容完整复制下来。到搜索引擎一查80% 的问题都有人遇到过。我在后面章节里也会列出一份高频报错对照表那是我实际安装中踩过的坑可以直接对照着处理。顺便提醒一句你不是在考试不需要背下所有命令。安装时照着文章复制粘贴遇到问题再去查学得最快。真正需要理解的是概念——路径是什么、包管理器在干嘛、报错怎么看——这三个概念理顺了安装就没有本质上的难度。2. Windows 部署从空白系统到 OpenClaw 跑起来2.1 环境准备确认系统位数与版本Windows 部署的第一步不是装 OpenClaw而是确认你的系统适合安装。OpenClaw 对 Windows 的基本要求是 Windows 10 64 位或更高版本Windows 11 更好老旧的 32 位系统基本不用考虑。怎么查看系统版本右键点击此电脑或我的电脑选择属性在弹出的窗口里能看到系统类型是 64 位还是 32 位以及 Windows 版本号。为什么这一步很关键因为有些第三方依赖库只提供 64 位版本你在 32 位系统上会反复安装失败而这个失败跟 OpenClaw 本身无关纯粹是地基不对。确认版本后建议先运行一轮 Windows Update把系统补丁打全。不要跳过这一步——某些运行库需要最新的系统补丁才能正常工作跳过会导致安装过程中出现莫名其妙的 DLL 缺失错误。2.2 安装 Git不只是版本管理工具如果你要部署 OpenClawGit 几乎是必装的哪怕你完全不搞代码。为什么因为 OpenClaw 的安装脚本可能会用到 Git 来拉取组件它的更新机制也依赖 Git。从官网下载 Git for Windows一路下一步安装即可。这里有一个关键选项需要注意安装到调整 PATH 环境变量那一步时建议选择Git from the command line and also from 3rd-party software即把 Git 加入系统 PATH。如果选错了后面你敲git --version会提示找不到命令。Git 安装完成后打开 PowerShell 输入git --version看到类似git version 2.x.x的输出就说明装好了。为什么我特别强调 Git因为很多零基础用户把 OpenClaw 当作普通软件以为双击安装包就行。但实际上它的运行机制决定了你绕不开 Git——它需要管理多个配置文件和组件版本没有 Git 就等于剪断了它的更新和回滚能力。2.3 安装 Python版本必须精准不能随意OpenClaw 基于 Python 开发所以 Python 是不可或缺的。但这里有个重要细节OpenClaw 对 Python 版本有明确要求通常要求 3.10 到 3.12 之间。装太老的版本如 3.8会缺语法支持装太新的版本如 3.13可能还没适配。推荐到 Python 官网下载对应版本。安装时有两个必选项勾选Add Python to PATH把 Python 加入环境变量选择Install Now默认安装添加 PATH 这个选项经常被人忽略。如果没有把 Python 加入 PATH你在终端敲python --version就会提示找不到命令。装完之后记得在 PowerShell 里验证python --version确认显示的版本号在支持范围内。此外还得提醒一句如果 Windows 系统自带的 Microsoft Store 里也提示可以安装 Python不要在安装过程中混用来源。建议从官网安装为主避免出现这个 Python 是商店版本那个是官网版本的混乱状态。2.4 安装 Node.js为什么一个 Python 项目还需要它听上去有点怪一个 Python 项目为什么需要 Node.js原因在于 OpenClaw 的部分前端界面和辅助工具链是基于 Node.js 构建的因此它也是安装清单里的成员之一。Node.js 同样有版本偏好推荐安装 LTS长期支持版。到 Node.js 官网下载 Windows 安装包一路下一步。装完验证命令是node --version和npm --version。npm 是 Node.js 自带的包管理器OpenClaw 在某些场景下会调用它来安装辅助组件。这里我要特别说明一个新手容易犯的错不要因为看到它不写 Python 代码为什么要装 Node就跳过这一步。跳过之后你会发现OpenClaw 主程序能启动但启动到一半提示缺少某个模块那个模块恰恰是 npm 负责装的。与其到时候回头补不如一开始就装齐。2.5 正式安装 OpenClaw两种方式与推荐选择环境准备好了终于可以装 OpenClaw 本体。官方通常提供两种安装方式pip 安装推荐的常规方式在 PowerShell 中执行pip install openclaw源码安装用 Git 克隆仓库后手动执行安装脚本我的建议是零基础用户先用 pip 安装。原因有两个第一pip 会自动处理 Python 依赖少操心第二后续卸载和更新方便一条命令搞定。源码安装更适合想二次开发的玩家对新人不友好。pip 安装命令执行后终端会滚动一堆输出这是在下载并安装依赖。根据网络情况可能持续几分钟。中间如果报网络超时或连接被重置通常不是 OpenClaw 的问题而是网络环境不稳定。这时可以给 pip 配置镜像源具体方法在后面的排错章节会细说。安装完成后的验证命令是openclaw --version。如果终端输出了版本号恭喜你主程序已经装好了。2.6 Windows 特有排错中文路径、杀软拦截与长路径Windows 上安装 OpenClaw 最常碰到的三类问题我在这章集中说一下。第一类中文用户名导致路径异常。错误特征是在某些步骤出现 Unicode 编码错误。前面提过解决思路安装到纯英文路径下。怎么确认当前用户目录有没有中文打开 PowerShell 输入echo $env:USERPROFILE如果输出的是C:\Users\张三那就建议手动将项目目录设置到D:\openclaw这种纯英文位置。第二类杀毒软件或 Windows Defender 拦截。OpenClaw 是开源工具某些杀软可能对它的一些文件产生误报。出现这种情况时可以临时关闭实时保护并把目录加入信任区。我不主张你永久关闭防护但安装阶段临时放行是合理的。第三类Windows 的长路径限制。这是个特别隐蔽的坑如果你的安装路径嵌套层级特别深比如C:\Users\你的名字\AppData\Local\Programs\Python\Python312\Lib\site-packages\openclaw\...可能触发 Windows 路径长度上限260 字符导致安装失败。解决办法是启用 Windows 长路径支持打开运行WinR输入gpedit.msc打开本地组策略编辑器路径定位到计算机配置 → 管理模板 → 系统 → 文件系统 → 启用 Win32 长路径设为已启用后重启。如果你用的是 Windows 家庭版没有组策略可以尝试缩短安装路径。3. macOS 部署M 芯片与 Intel 芯片下的差异与选择3.1 先装 Command Line ToolsmacOS 安装的敲门砖macOS 上部署 OpenClaw 的第一站通常不是 Homebrew而是 Command Line Tools命令行工具包。这个名字很直接它就是给 macOS 提供命令行工具的基础包里面包含编译器、Git 等一堆底层工具。打开终端在启动台 → 其他里输入以下命令xcode-select --install系统会弹窗提示安装确认后等待下载。这个过程可能比较久而且不显示进度条看起来像是卡住了——实际上并没有耐心等就行。装完后验证方式依然是git --version能输出版本号就说明 Command Line Tools 生效了。有一点要分开说Command Line Tools 和 Xcode 是两个东西。Xcode 是苹果的完整开发工具包非常大好几个 GBCommand Line Tools 只是它的命令行子集几百 MB。OpenClaw 只需要命令行工具包别误装了完整 Xcode。3.2 安装 HomebrewmacOS 上的包管理器之王有了命令行工具基础下一步是安装 Homebrew。它之于 macOS就像应用商店之于 iPhone但能力要强得多。安装命令是一行脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这个过程会要求你输入 Mac 的开机密码终端输入密码时不会显示任何字符属于正常现象然后开始下载。耐心等待。这里给新手提个醒安装 Homebrew 时不要看到长时间的静默就怀疑卡死。它在后台做的事很多下载文件、解压、建立目录结构通常需要两分钟以上网络差时甚至超过十分钟。判断有没有活着可以看菜单栏是否有网络活动或者同时开一个活动监视器看进程。Homebrew 装完用brew --version验证。注意在 Apple 芯片的 Mac 上Homebrew 的默认安装路径是/opt/homebrew而 Intel 芯片的 Mac 上是/usr/local。这个差异在装完 OpenClaw 后配置环境变量时很关键。3.3 Python 与 Node.jsmacOS 自带的 Python 千万别直接用macOS 系统本身自带了一个 Python 3但强烈不建议直接用这个版本部署 OpenClaw。为什么因为系统自带的 Python 主要是给系统工具用的权限和版本都受苹果控制直接往里面装第三方包容易触发系统保护机制SIP还可能污染系统环境。正确的做法是用 Homebrew 安装独立的 Pythonbrew install python3.12安装完成后用python3 --version验证。你可能会注意到终端敲python3和开新终端敲python3的结果可能不一样——这涉及 PATH 环境变量的问题后面专门讲。同理安装 Node.jsbrew install node这里想跟大家分享一个我在 macOS 上踩过的坑装 Homebrew 版的 Python 时它默认会装到/opt/homebrew/opt/python3.12/bin但这只是你的主 Python而你实际执行时调用的可能是系统自带的另一个版本。解决办法是使用brew link命令把 Homebrew 版设为默认或者通过虚拟环境的方式运行 OpenClaw。对于零基础用户我更推荐简单粗暴的做法在~/.zshrc文件里加一行环境变量指向 Homebrew 的 Python 路径。3.4 Apple 芯片M 系列与 Intel 芯片的部署差异macOS 上的 OpenClaw 部署和处理器架构强相关。Apple 芯片M1、M2、M3 等和 Intel 芯片在安装某些依赖时有着显著差异。怎么查看你的 Mac 是什么芯片点左上角苹果图标 → 关于本机在芯片一栏能看到 M 系列或 Intel 的字样。更准确的方法是终端里执行uname -m。如果输出arm64说明是 Apple 芯片如果输出x86_64说明是 Intel 芯片。这个差异为什么重要因为 OpenClaw 的部分底层依赖库需要编译本地代码。Apple 芯片和 Intel 芯片的指令集完全不同如果依赖库没有为对应架构提供预编译版本就会触发本地编译——此时你的 Mac 上必须有完整的编译工具链Command Line Tools 里已经带了且编译时间较长。好消息是目前主流的依赖库基本都已支持arm64架构遇到需要编译的情况不算多。另一个差异是 Homebrew 的安装路径。Apple 芯片 Mac 上 Homebrew 装在/opt/homebrewIntel 芯片装在/usr/local。在安装 OpenClaw 后如果出现command not found先检查当前用户的环境变量里是否写入了对应路径。这几乎是 Apple 芯片新手最常栽的跟头。具体的配置方法是在终端打开配置文件nano ~/.zshrc在文件末尾加一行以 Apple 芯片为例export PATH/opt/homebrew/bin:$PATH按CtrlX按Y按Enter保存退出然后执行source ~/.zshrc让配置立即生效。加完之后再用which python3确认路径。3.5 macOS 正式安装 OpenClaw 与权限处理环境齐了之后安装 OpenClaw 本体和 Windows 类似执行pip3 install openclaw如果你还没有创建虚拟环境建议花两分钟先建一个。这是个非常重要的习惯尤其是 macOS 上系统 Python 保护机制比较烦虚拟环境可以让你把 OpenClaw 的依赖全部隔离在一个独立目录里mkdir ~/openclaw-env cd ~/openclaw-env python3 -m venv venv source venv/bin/activate激活后你的终端提示符前面会出现(venv)字样。这时候执行pip install openclaw所有依赖都会装进这个虚拟环境不污染系统、不触发权限问题。后续每次使用 OpenClaw 前先执行一次source ~/openclaw-env/venv/bin/activate进入环境。还有一件事macOS 上首次运行 OpenClaw 时系统会弹窗提示无法打开因为无法验证开发者身份之类的问题。这是 Gatekeeper门禁在作怪。处理方式是到系统设置 → 隐私与安全性窗口找到对应的拦截记录点击仍要打开。如果它连仍要打开都不给可以在终端执行xattr -dr com.apple.quarantine 你的openclaw可执行文件路径清除隔离属性。这个命令只对你的下载文件生效不用惊慌。4. 双平台安装后的验证与高频报错排查4.1 验证清单装好之后怎么确认真的能用很多新手以为安装结束 安装成功其实不对。安装结束只是说文件复制完了能不能正常运行还需要验证。我整理了一份双平台通用的验证清单按顺序试一遍基本就能确认 OpenClaw 处于可用状态。第一步验证命令可用openclaw --version第二步查看帮助信息openclaw --help如果--help能正常输出一堆参数说明说明主程序解析正常。如果提示找不到某个配置文件或学习路径不要急这是首次运行需要生成配置。第三步冷启动测试。直接运行openclaw观察它是否能进入交互模式或至少输出日志。此时如果报错看提示是缺模块还是缺配置逐一解决。我特别想强调--version和--help的区别前者只检查主程序能不能加载后者会触发更完整的初始化逻辑。两个都过了才算初步没问题。4.2 高频报错对照表先看典型特征再对症下药为了让你排错时不那么慌我整理了一份高频报错对照表。这些错误不一定同时出现但覆盖面基本能到 80%错误提示关键词可能原因推荐处理方式command not found/不是内部或外部命令没有加入 PATH或当前环境没激活重新检查 PATH 配置macOS 检查 Homebrew 路径已建虚拟环境则确认激活pip: command not foundpip 未安装或未加入 PATHWindows 重装 Python 并勾选 Add to PATHmacOS 使用python3 -m pipModuleNotFoundError依赖模块缺失可能安装中断重装 OpenClawpip install --force-reinstall openclawSSL: CERTIFICATE_VERIFY_FAILED证书验证失败系统时间不对或证书链缺失同步系统时间macOS 在安装 Python 后运行安装证书脚本[Errno 13] Permission denied权限不足Windows 关闭杀软后重试macOS 避免用系统自带的 PythonUnicodeEncodeError编码问题通常与中文路径有关改用纯英文路径Windows 终端执行chcp 65001切 UTF-8fatal: unable to accessGit 拉取失败多为网络问题检查网络连接或配置 Git 镜像/代理断网重试MemoryError概率较低内存不足或某些库默认内存设置太小关闭占用内存大的应用后重试这些报错都不是 OpenClaw 本身傲慢更多是环境问题。你在排查时记住一个原则从底层往上层看。比如提示ModuleNotFoundError先确认 Python 本身版本对不对再看 pip 是否属于这个 Python最后看 OpenClaw 是不是装到这个 Python 里。很多人报错是因为系统里有两个 Pythonpip 装到了一个运行却用的是另一个。Windows 上用where python命令macOS 上用which python3能立刻看清当前指向的是哪个。4.3 网络超时与下载失败推荐一个稳妥的绕行方案安装过程中下载超时是最常见的问题尤其在中国大陆网络环境下访问海外源时。pip install openclaw如果反复因为网络超时失败可以换用国内镜像源比如清华或阿里云的 PyPI 镜像。临时使用只对本次生效pip install openclaw -i https://pypi.tuna.tsinghua.edu.cn/simple永久配置对以后所有安装生效是修改 pip 配置文件在用户主目录下创建pip.iniWindows或.pip/pip.confmacOS写入镜像地址。具体路径和格式可以搜一下网上资料很多不展开。还有一次我遇到的情况是 Git 拉取组件超时而不是 pip 超时。这个判断方法是看终端滚动的信息凡是Downloading ...开头的多半是 pip 在做凡是Cloning into ...开头的则是 Git 在做。Git 超时可以去查找 Git 代理配置或使用镜像仓库地址但这里提醒一句如果换了镜像还是拉不下来并且你的网络环境本身不太稳定不妨换个时间段重试。安装工具最怕的不是报错而是看起来没报错但实际缺了一部分组件所以每次安装完成后都要做一遍上面的验证清单。4.4 双平台虚拟环境一个养成类好习惯前面提到过 macOS 的虚拟环境其实 Windows 也建议这么做。为什么因为 OpenClaw 的依赖包里很可能有版本冲突——你之前装过的某个 Python 库可能和 OpenClaw 需要的版本不一致导致 OpenClaw 运行崩溃而你查半天也不知道原因。Python 虚拟环境venv解决的正是这个痛点。它相当于在你项目目录里建了一个独立的小屋所有依赖装进小屋和系统其他软件互不干扰。Windows 下创建方式如下python -m venv C:\openclaw-env\venv C:\openclaw-env\venv\Scripts\activate激活后命令行提示符前会出现(venv)。再次执行pip install openclaw所有东西都装在这个独立环境里。每次要使用时先激活用完可以deactivate退出。虚拟环境这个概念听起来高级但实际上就是你提前搭了个干净的工作台。对零基础用户来说它的价值在于你永远不用担心把系统搞坏。哪怕虚拟环境里的 OpenClaw 被你玩崩了删掉这个文件夹重新建一个就是系统依旧是干净的。5. 安装完成后接着做OpenClaw 的初始配置与一次快速体验5.1 初始化配置第一行命令该做什么装完 OpenClaw你还需要初始化配置才能正式使用。OpenClaw 在首次运行时会尝试创建一个配置目录通常在用户主目录下的.openclaw文件夹里面放着配置文件、日志等。你可以先手动执行一下看看效果openclaw init如果命令存在它会帮你生成默认配置并显示配置文件路径。如果提示没有这个命令也无妨——直接运行openclaw同样会触发首次初始化逻辑。我想强调一下配置文件的存在感。很多用户不知道怎么修改配置是因为找不到文件在哪。Windows 上一般路径是C:\Users\你的用户名\.openclaw\macOS 是/Users/你的用户名/.openclaw/。注意文件名以点开头属于隐藏目录如果图形界面里看不到记得在文件管理器里开启显示隐藏文件选项。5.2 配置本地模型接入从零开始跑通一次对话OpenClaw 本身是一个框架它需要对接具体的模型才能实现智能对话。这里要区分两种模型接入方式本地模型和云端模型 API。本地模型需要你有一定硬件基础独立显卡、大内存云端模型 API 则速度快但需要配置密钥。对于零基础用户如果想快速体验效果我建议先从本地小模型开始。选择模型时要看你的电脑配置16GB 内存的 Mac 可以尝试 7B 级别的量化模型Windows 如果显卡显存 8GB 以上可以上 13B 级别。我不推荐新手一上来就追求大模型因为加载速度和内存占用会迅速浇灭你的热情。配置方式通常是修改 OpenClaw 的配置文件把模型路径和参数填进去。具体字段名不同版本可能不同但核心思路一致指定模型类型、模型文件路径、上下文长度等。配置完重启 OpenClaw然后输入一句简单的问候看是否有正常回复。5.3 快速体验建议调低期待、先跑通流程我这里想给你打个预防针第一次成功安装 OpenClaw 后它的对话输出速度可能不像 ChatGPT 那么快尤其在本地模型下。这是正常的。框架的价值不在于让你瞬间拥有一个超级 AI而在于给它接上不同工具后它可以帮你做自动化任务——比如定时抓取信息、批量处理文件、调用自定义脚本。所以我的建议是第一周先不要想着配置复杂功能就把它当成一个本地对话助手熟悉它的性格和脾气——启动速度、回复风格、日志输出习惯。等跑通了基本流程再逐步研究如何接入更多工具。把预期放到先让它跑起来再让它跑好你会发现安装之后的路其实越走越宽。6. 部署后的日常维护升级、清理与最小化常见故障6.1 定期升级的两种姿势pip 与源码仓库OpenClaw 作为一个活跃维护的开源项目版本迭代速度比较快。我建议你养成定期升级的习惯否则某天早上打开它突然报错很可能是因为接口版本不匹配。用 pip 安装的话升级命令是pip install --upgrade openclaw用源码安装的话进入你克隆的仓库目录执行git pull拉取最新代码再重新执行安装脚本。两种方式都行但不要混着用。比如今天用 pip 装明天又下 GitHub 源码覆盖容易把依赖关系搞乱到时候查错会非常痛苦。6.2 常见启动故障的快筛方法先看日志再看配置如果排除了环境问题OpenClaw 启动时还是报错你需要学会看日志。日志通常存放在.openclaw目录下的logs文件夹里。日志文件名通常带日期内容记录了每次启动时的详细信息。排查思路是先打开最新日志拉到最后一百行左右。如果日志里有明显的ERROR或Traceback网上搜索那段核心报错文本。如果日志里没有错误但功能不正常检查配置文件里的模型路径是否有效——很多启动失败的假象真身其实只是模型文件路径写错了。这里有一个小技巧每次改动配置后先执行openclaw --version看有没有报解析错误再做完整启动。配置文件的语法错误是最容易排查的因为它会直接告诉你哪一行有问题。6.3 清理与卸载怎么把系统还原到安装之前试用一段时间后如果你决定不再使用或者准备彻底重装卸载需要稍微讲究一点。直接用操作系统自带的卸载入口往往删不干净因为 OpenClaw 的残留主要分布在三个位置Python 包目录pip 会自动卸载、用户主目录下的.openclaw文件夹、以及可能存在的缓存文件夹。比较彻底的卸载方式是命令优先pip uninstall openclaw然后手动删除~/.openclaw目录。Windows 上如果你建过虚拟环境直接把整个虚拟环境文件夹删掉即可。macOS 上同理。删完再检查一下有没有残留的 Git 仓库目录有就一并清理。如果你不打算卸载只是想让它的启动更快一些可以定期清理.openclaw下的过期刊日、缓存和临时文件。这种清理我每两个月会做一次能明显感觉到启动变利索。7. 我的个人部署心得一次看山跑死马的过来人总结把 Windows 和 macOS 两条路线都走完我想最后分享几个纯经验层面的东西这些是文档里不会写、但实际部署中非常重要的事。第一不要贪版本新。OpenClaw 的新版本不一定是稳定版我两次踩坑都是因为追求最新版结果依赖库还没适配。如果你是想用功能选经过社区验证的稳定版比什么都重要。第二尽量少碰各种一键安装脚本。市面上有些所谓OpenClaw 一键安装包听起来很省事但它会替你做很多你看不见的环境修改。这些修改一旦和你的机器环境冲突排查起来比手动安装麻烦十倍。我自己吃过的亏就是一键脚本给我装了某个旧版 Python导致后来所有手动装的东西全部不认那个版本最终只能重置环境重来。第三遇到问题找日志比自己瞎猜强。把错误关键词丢到搜索引擎、翻看一下项目的 Issues 区通常都能找到答案。很多开源项目的维护者会在 Issues 里回复用户的问题这些内容质量很高比技术文章更有针对性。最后还是那句话把 OpenClaw 装好只是拿到了一张入场券真正有趣的东西在它跑起来之后——让它帮你处理日常任务、对接各种工具、实现各种自动化想法那才是这个项目真正有价值的地方。希望这篇指南能帮你少走些弯路装得顺利玩得开心。
前阵子有位朋友在群里发消息说自己照着 OpenClaw 的 README 装三步就卡住了。不是网络问题不是电脑太老就是卡在终端里报了一个不算复杂的错误。我说你把报错发来看看结果发现是连最基本的路径和权限概念都没理顺。这其实不是个例——OpenClaw 这个开源个人智能助手框架名字听起来很酷安装门槛也不算高但对完全没接触过命令行的零基础用户来说Windows 和 macOS 两条路上都有不少隐藏的小坑。这篇文章就是给你这种听说过、想试试、但没系统玩过命令行的人准备的。OpenClaw 是什么这里不多展开你只需要知道它是一个能对接多种本地模型和工具、帮你自动化处理日常任务的个人助理框架。装好之后你可以通过对话让它查资料、生成内容、调用各类脚本。下面我会把 Windows 和 macOS 两条部署路径拆开来讲每一步都说明为什么要这么做、报错出现时怎么判断以及哪些是安装前必须补上的基础技能。整篇内容我尽量用一个过来人带你操作的口吻不堆术语但涉及关键概念时会给足解释保证小白能照着走完有点基础的人也能从中避掉几个我当年踩过的坑。1. 部署前的三样必要技能为什么零基础不等于零准备1.1 终端到底是个什么东西很多教程开篇就说打开终端执行以下命令但没人告诉你终端是什么、为什么非要跟它打交道。如果你之前只用过手机 App 或电脑桌面的图形界面那我建议先花十分钟把终端这个概念搞明白。终端Terminal本质上就是一个让你用文字给电脑下指令的窗口。你在图形界面里点鼠标能做的事终端里用一行命令也同样能做甚至能做更多。Windows 上叫 PowerShell 或命令提示符macOS 上叫终端Terminal.app。OpenClaw 的安装过程之所以离不开终端是因为它本质是一个命令行工具——它的安装脚本、配置文件、启动方式都是围绕终端设计的你不可能绕过它。我见过不少新人一看到黑底白字的窗口就发怵其实完全没必要。你只需要掌握三件事第一命令分输入和回车确认两步第二命令窗口里的文字不会弄坏电脑最多报个错第三大部分错误提示都有规律复制到搜索引擎里就能找到答案。抱着这个心态终端就是你的工具箱不是老虎。1.2 必补基础之一路径和目录的底层逻辑安装 OpenClaw 时你会频繁和路径打交道。什么是路径就是电脑上某个文件或文件夹的门牌地址。Windows 的路径长这样C:\Users\你的用户名\DownloadsmacOS 长这样/Users/你的用户名/Downloads。两者一个用反斜杠\一个用正斜杠/这是很多命令在双平台表现不一致的根源。在终端里你必须知道两件事当前在哪要去哪。输入pwdPrint Working Directory可以显示当前所在目录输入lsmacOS/Linux或dirWindows可以查看当前目录下有什么。安装 OpenClaw 时官方给你的命令默认是在用户主目录下执行的如果在别的目录执行导致找不到文件八成就是路径问题。还有一个与路径有关的坑尽量选择纯英文路径安装。如果你的 Windows 用户名是中文比如C:\Users\张三某些开源工具对中文路径支持并不完美会在莫名其妙的地方报编码错误。解决办法是装到一个纯英文路径下比如D:\tools\openclaw。这不算歧视中文纯粹是历史兼容性原因能避开就避开。1.3 必补基础之二包管理器是应用商店的命令行版本你在手机上下 App 是不是都走应用商店电脑上的包管理器也是类似的东西。Windows 上的winget、macOS 上的Homebrew常简称 brew还有编程语言级别的pipPython 的包管理器都是命令行版应用商店。OpenClaw 依赖 Python、Git、Node.js 等一堆运行环境你当然可以去官网一个个下载安装包然后用鼠标点下一步但那样既慢又容易漏。更专业的做法是先安装包管理器再用几行命令把这些依赖统一装好。包管理器的好处是能自动处理依赖关系——比如某个工具需要特定版本的另一个库包管理器会帮你自动装好而不需要你手动去找。你可能想问那我能不能完全不学包管理器全用安装包可以但操作量会翻倍而且后续 OpenClaw 更新时用包管理器只需要一条命令手动安装却要重新下载覆盖非常麻烦。所以既然要零基础部署不如从一开始就走专业路线。1.4 必补基础之三读懂报错比背命令更重要零基础用户最常犯的一个错误是以为命令执行之后就万事大吉。实际上终端里执行完命令屏幕上会返回一堆信息。这些信息至少分为两类正常的输出和错误提示。错误提示通常以Error、Traceback、fatal、command not found等关键词开头。你需要培养的能力是报错出现时不要慌不要立刻关掉窗口先把报错内容完整复制下来。到搜索引擎一查80% 的问题都有人遇到过。我在后面章节里也会列出一份高频报错对照表那是我实际安装中踩过的坑可以直接对照着处理。顺便提醒一句你不是在考试不需要背下所有命令。安装时照着文章复制粘贴遇到问题再去查学得最快。真正需要理解的是概念——路径是什么、包管理器在干嘛、报错怎么看——这三个概念理顺了安装就没有本质上的难度。2. Windows 部署从空白系统到 OpenClaw 跑起来2.1 环境准备确认系统位数与版本Windows 部署的第一步不是装 OpenClaw而是确认你的系统适合安装。OpenClaw 对 Windows 的基本要求是 Windows 10 64 位或更高版本Windows 11 更好老旧的 32 位系统基本不用考虑。怎么查看系统版本右键点击此电脑或我的电脑选择属性在弹出的窗口里能看到系统类型是 64 位还是 32 位以及 Windows 版本号。为什么这一步很关键因为有些第三方依赖库只提供 64 位版本你在 32 位系统上会反复安装失败而这个失败跟 OpenClaw 本身无关纯粹是地基不对。确认版本后建议先运行一轮 Windows Update把系统补丁打全。不要跳过这一步——某些运行库需要最新的系统补丁才能正常工作跳过会导致安装过程中出现莫名其妙的 DLL 缺失错误。2.2 安装 Git不只是版本管理工具如果你要部署 OpenClawGit 几乎是必装的哪怕你完全不搞代码。为什么因为 OpenClaw 的安装脚本可能会用到 Git 来拉取组件它的更新机制也依赖 Git。从官网下载 Git for Windows一路下一步安装即可。这里有一个关键选项需要注意安装到调整 PATH 环境变量那一步时建议选择Git from the command line and also from 3rd-party software即把 Git 加入系统 PATH。如果选错了后面你敲git --version会提示找不到命令。Git 安装完成后打开 PowerShell 输入git --version看到类似git version 2.x.x的输出就说明装好了。为什么我特别强调 Git因为很多零基础用户把 OpenClaw 当作普通软件以为双击安装包就行。但实际上它的运行机制决定了你绕不开 Git——它需要管理多个配置文件和组件版本没有 Git 就等于剪断了它的更新和回滚能力。2.3 安装 Python版本必须精准不能随意OpenClaw 基于 Python 开发所以 Python 是不可或缺的。但这里有个重要细节OpenClaw 对 Python 版本有明确要求通常要求 3.10 到 3.12 之间。装太老的版本如 3.8会缺语法支持装太新的版本如 3.13可能还没适配。推荐到 Python 官网下载对应版本。安装时有两个必选项勾选Add Python to PATH把 Python 加入环境变量选择Install Now默认安装添加 PATH 这个选项经常被人忽略。如果没有把 Python 加入 PATH你在终端敲python --version就会提示找不到命令。装完之后记得在 PowerShell 里验证python --version确认显示的版本号在支持范围内。此外还得提醒一句如果 Windows 系统自带的 Microsoft Store 里也提示可以安装 Python不要在安装过程中混用来源。建议从官网安装为主避免出现这个 Python 是商店版本那个是官网版本的混乱状态。2.4 安装 Node.js为什么一个 Python 项目还需要它听上去有点怪一个 Python 项目为什么需要 Node.js原因在于 OpenClaw 的部分前端界面和辅助工具链是基于 Node.js 构建的因此它也是安装清单里的成员之一。Node.js 同样有版本偏好推荐安装 LTS长期支持版。到 Node.js 官网下载 Windows 安装包一路下一步。装完验证命令是node --version和npm --version。npm 是 Node.js 自带的包管理器OpenClaw 在某些场景下会调用它来安装辅助组件。这里我要特别说明一个新手容易犯的错不要因为看到它不写 Python 代码为什么要装 Node就跳过这一步。跳过之后你会发现OpenClaw 主程序能启动但启动到一半提示缺少某个模块那个模块恰恰是 npm 负责装的。与其到时候回头补不如一开始就装齐。2.5 正式安装 OpenClaw两种方式与推荐选择环境准备好了终于可以装 OpenClaw 本体。官方通常提供两种安装方式pip 安装推荐的常规方式在 PowerShell 中执行pip install openclaw源码安装用 Git 克隆仓库后手动执行安装脚本我的建议是零基础用户先用 pip 安装。原因有两个第一pip 会自动处理 Python 依赖少操心第二后续卸载和更新方便一条命令搞定。源码安装更适合想二次开发的玩家对新人不友好。pip 安装命令执行后终端会滚动一堆输出这是在下载并安装依赖。根据网络情况可能持续几分钟。中间如果报网络超时或连接被重置通常不是 OpenClaw 的问题而是网络环境不稳定。这时可以给 pip 配置镜像源具体方法在后面的排错章节会细说。安装完成后的验证命令是openclaw --version。如果终端输出了版本号恭喜你主程序已经装好了。2.6 Windows 特有排错中文路径、杀软拦截与长路径Windows 上安装 OpenClaw 最常碰到的三类问题我在这章集中说一下。第一类中文用户名导致路径异常。错误特征是在某些步骤出现 Unicode 编码错误。前面提过解决思路安装到纯英文路径下。怎么确认当前用户目录有没有中文打开 PowerShell 输入echo $env:USERPROFILE如果输出的是C:\Users\张三那就建议手动将项目目录设置到D:\openclaw这种纯英文位置。第二类杀毒软件或 Windows Defender 拦截。OpenClaw 是开源工具某些杀软可能对它的一些文件产生误报。出现这种情况时可以临时关闭实时保护并把目录加入信任区。我不主张你永久关闭防护但安装阶段临时放行是合理的。第三类Windows 的长路径限制。这是个特别隐蔽的坑如果你的安装路径嵌套层级特别深比如C:\Users\你的名字\AppData\Local\Programs\Python\Python312\Lib\site-packages\openclaw\...可能触发 Windows 路径长度上限260 字符导致安装失败。解决办法是启用 Windows 长路径支持打开运行WinR输入gpedit.msc打开本地组策略编辑器路径定位到计算机配置 → 管理模板 → 系统 → 文件系统 → 启用 Win32 长路径设为已启用后重启。如果你用的是 Windows 家庭版没有组策略可以尝试缩短安装路径。3. macOS 部署M 芯片与 Intel 芯片下的差异与选择3.1 先装 Command Line ToolsmacOS 安装的敲门砖macOS 上部署 OpenClaw 的第一站通常不是 Homebrew而是 Command Line Tools命令行工具包。这个名字很直接它就是给 macOS 提供命令行工具的基础包里面包含编译器、Git 等一堆底层工具。打开终端在启动台 → 其他里输入以下命令xcode-select --install系统会弹窗提示安装确认后等待下载。这个过程可能比较久而且不显示进度条看起来像是卡住了——实际上并没有耐心等就行。装完后验证方式依然是git --version能输出版本号就说明 Command Line Tools 生效了。有一点要分开说Command Line Tools 和 Xcode 是两个东西。Xcode 是苹果的完整开发工具包非常大好几个 GBCommand Line Tools 只是它的命令行子集几百 MB。OpenClaw 只需要命令行工具包别误装了完整 Xcode。3.2 安装 HomebrewmacOS 上的包管理器之王有了命令行工具基础下一步是安装 Homebrew。它之于 macOS就像应用商店之于 iPhone但能力要强得多。安装命令是一行脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这个过程会要求你输入 Mac 的开机密码终端输入密码时不会显示任何字符属于正常现象然后开始下载。耐心等待。这里给新手提个醒安装 Homebrew 时不要看到长时间的静默就怀疑卡死。它在后台做的事很多下载文件、解压、建立目录结构通常需要两分钟以上网络差时甚至超过十分钟。判断有没有活着可以看菜单栏是否有网络活动或者同时开一个活动监视器看进程。Homebrew 装完用brew --version验证。注意在 Apple 芯片的 Mac 上Homebrew 的默认安装路径是/opt/homebrew而 Intel 芯片的 Mac 上是/usr/local。这个差异在装完 OpenClaw 后配置环境变量时很关键。3.3 Python 与 Node.jsmacOS 自带的 Python 千万别直接用macOS 系统本身自带了一个 Python 3但强烈不建议直接用这个版本部署 OpenClaw。为什么因为系统自带的 Python 主要是给系统工具用的权限和版本都受苹果控制直接往里面装第三方包容易触发系统保护机制SIP还可能污染系统环境。正确的做法是用 Homebrew 安装独立的 Pythonbrew install python3.12安装完成后用python3 --version验证。你可能会注意到终端敲python3和开新终端敲python3的结果可能不一样——这涉及 PATH 环境变量的问题后面专门讲。同理安装 Node.jsbrew install node这里想跟大家分享一个我在 macOS 上踩过的坑装 Homebrew 版的 Python 时它默认会装到/opt/homebrew/opt/python3.12/bin但这只是你的主 Python而你实际执行时调用的可能是系统自带的另一个版本。解决办法是使用brew link命令把 Homebrew 版设为默认或者通过虚拟环境的方式运行 OpenClaw。对于零基础用户我更推荐简单粗暴的做法在~/.zshrc文件里加一行环境变量指向 Homebrew 的 Python 路径。3.4 Apple 芯片M 系列与 Intel 芯片的部署差异macOS 上的 OpenClaw 部署和处理器架构强相关。Apple 芯片M1、M2、M3 等和 Intel 芯片在安装某些依赖时有着显著差异。怎么查看你的 Mac 是什么芯片点左上角苹果图标 → 关于本机在芯片一栏能看到 M 系列或 Intel 的字样。更准确的方法是终端里执行uname -m。如果输出arm64说明是 Apple 芯片如果输出x86_64说明是 Intel 芯片。这个差异为什么重要因为 OpenClaw 的部分底层依赖库需要编译本地代码。Apple 芯片和 Intel 芯片的指令集完全不同如果依赖库没有为对应架构提供预编译版本就会触发本地编译——此时你的 Mac 上必须有完整的编译工具链Command Line Tools 里已经带了且编译时间较长。好消息是目前主流的依赖库基本都已支持arm64架构遇到需要编译的情况不算多。另一个差异是 Homebrew 的安装路径。Apple 芯片 Mac 上 Homebrew 装在/opt/homebrewIntel 芯片装在/usr/local。在安装 OpenClaw 后如果出现command not found先检查当前用户的环境变量里是否写入了对应路径。这几乎是 Apple 芯片新手最常栽的跟头。具体的配置方法是在终端打开配置文件nano ~/.zshrc在文件末尾加一行以 Apple 芯片为例export PATH/opt/homebrew/bin:$PATH按CtrlX按Y按Enter保存退出然后执行source ~/.zshrc让配置立即生效。加完之后再用which python3确认路径。3.5 macOS 正式安装 OpenClaw 与权限处理环境齐了之后安装 OpenClaw 本体和 Windows 类似执行pip3 install openclaw如果你还没有创建虚拟环境建议花两分钟先建一个。这是个非常重要的习惯尤其是 macOS 上系统 Python 保护机制比较烦虚拟环境可以让你把 OpenClaw 的依赖全部隔离在一个独立目录里mkdir ~/openclaw-env cd ~/openclaw-env python3 -m venv venv source venv/bin/activate激活后你的终端提示符前面会出现(venv)字样。这时候执行pip install openclaw所有依赖都会装进这个虚拟环境不污染系统、不触发权限问题。后续每次使用 OpenClaw 前先执行一次source ~/openclaw-env/venv/bin/activate进入环境。还有一件事macOS 上首次运行 OpenClaw 时系统会弹窗提示无法打开因为无法验证开发者身份之类的问题。这是 Gatekeeper门禁在作怪。处理方式是到系统设置 → 隐私与安全性窗口找到对应的拦截记录点击仍要打开。如果它连仍要打开都不给可以在终端执行xattr -dr com.apple.quarantine 你的openclaw可执行文件路径清除隔离属性。这个命令只对你的下载文件生效不用惊慌。4. 双平台安装后的验证与高频报错排查4.1 验证清单装好之后怎么确认真的能用很多新手以为安装结束 安装成功其实不对。安装结束只是说文件复制完了能不能正常运行还需要验证。我整理了一份双平台通用的验证清单按顺序试一遍基本就能确认 OpenClaw 处于可用状态。第一步验证命令可用openclaw --version第二步查看帮助信息openclaw --help如果--help能正常输出一堆参数说明说明主程序解析正常。如果提示找不到某个配置文件或学习路径不要急这是首次运行需要生成配置。第三步冷启动测试。直接运行openclaw观察它是否能进入交互模式或至少输出日志。此时如果报错看提示是缺模块还是缺配置逐一解决。我特别想强调--version和--help的区别前者只检查主程序能不能加载后者会触发更完整的初始化逻辑。两个都过了才算初步没问题。4.2 高频报错对照表先看典型特征再对症下药为了让你排错时不那么慌我整理了一份高频报错对照表。这些错误不一定同时出现但覆盖面基本能到 80%错误提示关键词可能原因推荐处理方式command not found/不是内部或外部命令没有加入 PATH或当前环境没激活重新检查 PATH 配置macOS 检查 Homebrew 路径已建虚拟环境则确认激活pip: command not foundpip 未安装或未加入 PATHWindows 重装 Python 并勾选 Add to PATHmacOS 使用python3 -m pipModuleNotFoundError依赖模块缺失可能安装中断重装 OpenClawpip install --force-reinstall openclawSSL: CERTIFICATE_VERIFY_FAILED证书验证失败系统时间不对或证书链缺失同步系统时间macOS 在安装 Python 后运行安装证书脚本[Errno 13] Permission denied权限不足Windows 关闭杀软后重试macOS 避免用系统自带的 PythonUnicodeEncodeError编码问题通常与中文路径有关改用纯英文路径Windows 终端执行chcp 65001切 UTF-8fatal: unable to accessGit 拉取失败多为网络问题检查网络连接或配置 Git 镜像/代理断网重试MemoryError概率较低内存不足或某些库默认内存设置太小关闭占用内存大的应用后重试这些报错都不是 OpenClaw 本身傲慢更多是环境问题。你在排查时记住一个原则从底层往上层看。比如提示ModuleNotFoundError先确认 Python 本身版本对不对再看 pip 是否属于这个 Python最后看 OpenClaw 是不是装到这个 Python 里。很多人报错是因为系统里有两个 Pythonpip 装到了一个运行却用的是另一个。Windows 上用where python命令macOS 上用which python3能立刻看清当前指向的是哪个。4.3 网络超时与下载失败推荐一个稳妥的绕行方案安装过程中下载超时是最常见的问题尤其在中国大陆网络环境下访问海外源时。pip install openclaw如果反复因为网络超时失败可以换用国内镜像源比如清华或阿里云的 PyPI 镜像。临时使用只对本次生效pip install openclaw -i https://pypi.tuna.tsinghua.edu.cn/simple永久配置对以后所有安装生效是修改 pip 配置文件在用户主目录下创建pip.iniWindows或.pip/pip.confmacOS写入镜像地址。具体路径和格式可以搜一下网上资料很多不展开。还有一次我遇到的情况是 Git 拉取组件超时而不是 pip 超时。这个判断方法是看终端滚动的信息凡是Downloading ...开头的多半是 pip 在做凡是Cloning into ...开头的则是 Git 在做。Git 超时可以去查找 Git 代理配置或使用镜像仓库地址但这里提醒一句如果换了镜像还是拉不下来并且你的网络环境本身不太稳定不妨换个时间段重试。安装工具最怕的不是报错而是看起来没报错但实际缺了一部分组件所以每次安装完成后都要做一遍上面的验证清单。4.4 双平台虚拟环境一个养成类好习惯前面提到过 macOS 的虚拟环境其实 Windows 也建议这么做。为什么因为 OpenClaw 的依赖包里很可能有版本冲突——你之前装过的某个 Python 库可能和 OpenClaw 需要的版本不一致导致 OpenClaw 运行崩溃而你查半天也不知道原因。Python 虚拟环境venv解决的正是这个痛点。它相当于在你项目目录里建了一个独立的小屋所有依赖装进小屋和系统其他软件互不干扰。Windows 下创建方式如下python -m venv C:\openclaw-env\venv C:\openclaw-env\venv\Scripts\activate激活后命令行提示符前会出现(venv)。再次执行pip install openclaw所有东西都装在这个独立环境里。每次要使用时先激活用完可以deactivate退出。虚拟环境这个概念听起来高级但实际上就是你提前搭了个干净的工作台。对零基础用户来说它的价值在于你永远不用担心把系统搞坏。哪怕虚拟环境里的 OpenClaw 被你玩崩了删掉这个文件夹重新建一个就是系统依旧是干净的。5. 安装完成后接着做OpenClaw 的初始配置与一次快速体验5.1 初始化配置第一行命令该做什么装完 OpenClaw你还需要初始化配置才能正式使用。OpenClaw 在首次运行时会尝试创建一个配置目录通常在用户主目录下的.openclaw文件夹里面放着配置文件、日志等。你可以先手动执行一下看看效果openclaw init如果命令存在它会帮你生成默认配置并显示配置文件路径。如果提示没有这个命令也无妨——直接运行openclaw同样会触发首次初始化逻辑。我想强调一下配置文件的存在感。很多用户不知道怎么修改配置是因为找不到文件在哪。Windows 上一般路径是C:\Users\你的用户名\.openclaw\macOS 是/Users/你的用户名/.openclaw/。注意文件名以点开头属于隐藏目录如果图形界面里看不到记得在文件管理器里开启显示隐藏文件选项。5.2 配置本地模型接入从零开始跑通一次对话OpenClaw 本身是一个框架它需要对接具体的模型才能实现智能对话。这里要区分两种模型接入方式本地模型和云端模型 API。本地模型需要你有一定硬件基础独立显卡、大内存云端模型 API 则速度快但需要配置密钥。对于零基础用户如果想快速体验效果我建议先从本地小模型开始。选择模型时要看你的电脑配置16GB 内存的 Mac 可以尝试 7B 级别的量化模型Windows 如果显卡显存 8GB 以上可以上 13B 级别。我不推荐新手一上来就追求大模型因为加载速度和内存占用会迅速浇灭你的热情。配置方式通常是修改 OpenClaw 的配置文件把模型路径和参数填进去。具体字段名不同版本可能不同但核心思路一致指定模型类型、模型文件路径、上下文长度等。配置完重启 OpenClaw然后输入一句简单的问候看是否有正常回复。5.3 快速体验建议调低期待、先跑通流程我这里想给你打个预防针第一次成功安装 OpenClaw 后它的对话输出速度可能不像 ChatGPT 那么快尤其在本地模型下。这是正常的。框架的价值不在于让你瞬间拥有一个超级 AI而在于给它接上不同工具后它可以帮你做自动化任务——比如定时抓取信息、批量处理文件、调用自定义脚本。所以我的建议是第一周先不要想着配置复杂功能就把它当成一个本地对话助手熟悉它的性格和脾气——启动速度、回复风格、日志输出习惯。等跑通了基本流程再逐步研究如何接入更多工具。把预期放到先让它跑起来再让它跑好你会发现安装之后的路其实越走越宽。6. 部署后的日常维护升级、清理与最小化常见故障6.1 定期升级的两种姿势pip 与源码仓库OpenClaw 作为一个活跃维护的开源项目版本迭代速度比较快。我建议你养成定期升级的习惯否则某天早上打开它突然报错很可能是因为接口版本不匹配。用 pip 安装的话升级命令是pip install --upgrade openclaw用源码安装的话进入你克隆的仓库目录执行git pull拉取最新代码再重新执行安装脚本。两种方式都行但不要混着用。比如今天用 pip 装明天又下 GitHub 源码覆盖容易把依赖关系搞乱到时候查错会非常痛苦。6.2 常见启动故障的快筛方法先看日志再看配置如果排除了环境问题OpenClaw 启动时还是报错你需要学会看日志。日志通常存放在.openclaw目录下的logs文件夹里。日志文件名通常带日期内容记录了每次启动时的详细信息。排查思路是先打开最新日志拉到最后一百行左右。如果日志里有明显的ERROR或Traceback网上搜索那段核心报错文本。如果日志里没有错误但功能不正常检查配置文件里的模型路径是否有效——很多启动失败的假象真身其实只是模型文件路径写错了。这里有一个小技巧每次改动配置后先执行openclaw --version看有没有报解析错误再做完整启动。配置文件的语法错误是最容易排查的因为它会直接告诉你哪一行有问题。6.3 清理与卸载怎么把系统还原到安装之前试用一段时间后如果你决定不再使用或者准备彻底重装卸载需要稍微讲究一点。直接用操作系统自带的卸载入口往往删不干净因为 OpenClaw 的残留主要分布在三个位置Python 包目录pip 会自动卸载、用户主目录下的.openclaw文件夹、以及可能存在的缓存文件夹。比较彻底的卸载方式是命令优先pip uninstall openclaw然后手动删除~/.openclaw目录。Windows 上如果你建过虚拟环境直接把整个虚拟环境文件夹删掉即可。macOS 上同理。删完再检查一下有没有残留的 Git 仓库目录有就一并清理。如果你不打算卸载只是想让它的启动更快一些可以定期清理.openclaw下的过期刊日、缓存和临时文件。这种清理我每两个月会做一次能明显感觉到启动变利索。7. 我的个人部署心得一次看山跑死马的过来人总结把 Windows 和 macOS 两条路线都走完我想最后分享几个纯经验层面的东西这些是文档里不会写、但实际部署中非常重要的事。第一不要贪版本新。OpenClaw 的新版本不一定是稳定版我两次踩坑都是因为追求最新版结果依赖库还没适配。如果你是想用功能选经过社区验证的稳定版比什么都重要。第二尽量少碰各种一键安装脚本。市面上有些所谓OpenClaw 一键安装包听起来很省事但它会替你做很多你看不见的环境修改。这些修改一旦和你的机器环境冲突排查起来比手动安装麻烦十倍。我自己吃过的亏就是一键脚本给我装了某个旧版 Python导致后来所有手动装的东西全部不认那个版本最终只能重置环境重来。第三遇到问题找日志比自己瞎猜强。把错误关键词丢到搜索引擎、翻看一下项目的 Issues 区通常都能找到答案。很多开源项目的维护者会在 Issues 里回复用户的问题这些内容质量很高比技术文章更有针对性。最后还是那句话把 OpenClaw 装好只是拿到了一张入场券真正有趣的东西在它跑起来之后——让它帮你处理日常任务、对接各种工具、实现各种自动化想法那才是这个项目真正有价值的地方。希望这篇指南能帮你少走些弯路装得顺利玩得开心。
