第一次在终端里敲命令去装一个软件很多人心里是发怵的。我自己也是从那个状态过来的看着黑乎乎的窗口生怕敲错了把系统搞坏。但如果你想用上 OpenClaw 这种 AI 代理工具这一步必须迈出去。OpenClaw 简单来说是一个跑在命令行里的开源 AI 代理框架你给它一段自然语言任务它会自己拆解步骤调用你配置好的模型服务把搜索、整理、写作这类重复劳动帮你做完。它不像那些带图形界面的软件装上就能点鼠标操作但这恰恰是它的优势轻量、透明、可控而且对个人使用完全免费。这篇指南我尽量写得特别啰嗦因为我的目标读者就是纯新手。Mac 电脑、没怎么用过终端、不知道环境变量是什么东西。我会从怎么打开终端开始一步步带你把基础环境装好再用最简单的方式把 OpenClaw 跑起来最后让它真实执行一个任务。文章里所有命令我都会解释它是干什么的出错之后怎么排查哪些坑是我实际踩过、希望你能绕开的尽量都写进去。1. 动手前的三件事确认配置、认识终端、备好密钥1.1 查看你的Mac芯片和系统版本安装之前先花两分钟确认一下你手上这台机器的硬件情况。2020 年之后的 Mac 基本都是 M 系列芯片M1、M2、M3、M4更早的是 Intel 芯片。为什么非要确认这个因为后面我们要装包管理工具它会根据芯片类型选择对应的安装包和编译架构。选错架构装出来的程序会有一种很迷惑的现象命令能找到但一运行就报错或者性能明显不对。查看方法很简单点击屏幕左上角的苹果菜单选择系统信息有的系统版本叫关于本机弹出来的窗口里就能看到芯片一栏。如果写的是Apple M2那这就是 M 芯片如果写的是类似Intel Core i5这样的字样那就是 Intel 芯片。系统版本也在同一屏能看到OpenClaw 对 macOS 版本没有太苛刻的要求但别低于当前主流版本太多建议至少保持在一个 macOS 大版本内比如系统设置里还能正常收到安全更新就行。另外顺带提醒一句内存建议 8GB 起步。我实测过 8GB 内存跑 OpenClaw 是够用的但如果你同时开着十几个浏览器标签、剪辑软件、聊天工具再让模型服务跑长任务风扇就会开始唱歌了。如果你只有 8GB跑任务之前把不用的应用随手关掉体验会好很多。1.2 认识终端你只需要会六个命令很多人一听命令行就紧张其实日常用到的命令非常少。我们不是要学编程只要能完成这几件事进入目录、看当前在哪、创建文件夹、复制文件、查看命令帮助、清除屏幕。我把对应的命令列出来pwd显示当前所在的目录路径ls列出当前目录下的文件和文件夹cd 目录名进入某个目录比如cd Downloads就进入下载文件夹mkdir 文件夹名创建一个新文件夹cp 文件1 文件2复制文件clear清空终端窗口让界面干净一些你先打开终端练两下。打开终端的姿势有两种一种是按住 Command 空格输入终端或者Terminal回车另一种是在访达的应用程序里找到实用工具文件夹终端就在里面。打开之后你看到的是一个白色或者黑色的窗口前面有一个类似你的电脑名:~ 用户名$这样的提示符。这个~符号表示你的用户主目录所有个人文件都在这个目录底下。我第一次用终端的时候最慌的就是不知道自己在哪。后来学乖了每敲一个改变位置的命令之前先敲一下pwd确认了再走。这个习惯我现在都保留着也推荐你试试。还有一个细节终端里面粘贴命令不能用 Command V而是 Command Shift V如果发现粘贴不出来多半是快捷键按错了。1.3 提前注册好模型服务的API密钥OpenClaw 本身只是一个调度框架真正干活的大脑是各家模型服务商的模型接口。所以你需要先去一家模型服务商的官网注册一个账户然后在个人后台找到API 密钥或者API Keys相关的页面创建一个密钥。创建密钥时有几个细节第一密钥是一长串字符一般以sk-开头一定要复制保存好有些网站只显示一次关掉页面就再也看不到了第二建议创建密钥的时候就设置好额度上限比如每月限制少量金额这样就算密钥意外泄露损失也可控第三不要把这个密钥分享给任何人也不要贴到公开的社交平台上。很多新手会卡在这一步因为注册需要绑付款方式。说实话现在的模型服务商基本都会送一些免费额度够你测试玩几天。如果你实在不想绑卡也可以找一些提供免费测试密钥的公共模型服务平台试试但那些稳定性差一些我还是建议注册一个正规服务商的账号哪怕先充比较少心里更踏实。密钥拿到手之后先存在一个备忘录里后面配置的时候要用。2. 基础环境搭建装好工具箱后面才不折腾2.1 先安装macOS命令行开发者工具Mac 系统虽然自带了终端但它默认没有装编译软件要用的那一套底层工具集。在装 OpenClaw 之前我们要先把这套地基打好。好在苹果官方提供了一键安装方式。打开终端输入下面这行命令回车xcode-select --install系统会弹出一个安装窗口点击安装然后等待它下载完成。这一步下载的时间取决于你的网速有时候会显得像卡住了一样其实是在后台慢慢拉。耐心等就行。如果弹出软件已安装或者提示你已经有了那就直接跳过这步。为什么非要装这个因为很多开源软件在安装过程中需要临时编译一些组件而编译就需要编译器。这套开发者工具就包含了编译器、链接器等基础组件。你不需要会写 C 语言只需要知道它是给后续安装过程当脚手架用的。这一步是坑最少的一步也是最容易被忽略的一步。不少新手直接跳过去装 OpenClaw结果报错信息一堆回头一问十有八九是这一步没装。2.2 用Homebrew管理软件包接下来要装一个叫 Homebrew 的包管理工具。你可以把它理解成 Mac 上的应用商店只不过它管的不是图形软件而是命令行工具和开发库。以后你装任何开源命令行软件基本都能通过它一条命令搞定不用自己去网上找安装包非常省心。安装命令如下/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这条命令的意思是下载 Homebrew 的官方安装脚本然后用 bash 执行它。执行过程中会要求你输入电脑的开机密码这是正常的因为安装过程中需要向系统目录写入文件。输入密码时屏幕上不会显示任何字符你不要以为键盘坏了只管输完回车。安装完 Homebrew 之后它会提示你运行两行设置环境变量的命令。这一步很多人会忽略结果后面一运行brew就说找不到。如果你安装完屏幕上有提示就老老实实把那两行命令复制粘贴执行一遍。如果不确定是否设置成功可以新开一个终端窗口输入brew --version如果能看到版本号数字说明成功了。这里我想多讲两句Homebrew 在安装过程中会访问 GitHub 下载一些核心文件如果你所在网络的国际访问速度不理想可能会卡住。遇到这种情况可以搜索Homebrew 镜像源这五个字网上有大量的社区镜像教程。镜像源就是把这些官方文件同步到国内的服务器你通过国内地址下载速度会快很多。换源操作不复杂照着教程复制几条命令就行记得换完之后再执行一遍brew update验证。2.3 通过Homebrew安装Git和运行环境Homebrew 装好之后我们就要通过它来安装 OpenClaw 需要的几个基础依赖。首先是 Git它是一个版本管理工具OpenClaw 的安装脚本和后续更新都要用到它。第二个是运行时环境因为 OpenClaw 的某些功能模块依赖 Python 3 或者 Node.js具体看你选哪种安装方式。我建议你把两者都装上省得后面遇到某个功能缺环境。在终端里执行brew install git python node这行命令会自动帮你安装这三个东西。执行的时候 Homebrew 可能会先自动更新一下自己的索引这个过程也会花一些时间属正常现象。装完之后可以在终端里分别输入以下命令确认git --version python3 --version node -v只要都能输出版本号就说明环境齐了。这里要说一个关键细节Mac 系统自带了 Python但是版本通常比较旧我们安装的是 Python 3所以运行的时候要用python3而不是python。很多教程里写python你在 Mac 上执行会发现出来的是旧版本甚至直接报错这个坑一定要记住。2.4 给终端工具做一次全面体检环境装到这里其实已经能安装 OpenClaw 了。但我想多插一步建议你顺手装一下 Xcode 的命令行完整工具包。之前我们用的是轻量安装有时候一些边缘工具还是缺失的干脆装全避免后续莫名其妙报错。执行brew install --cask xcode-command-line-tools这条命令会把完整的开发者工具包补全。整个过程可能稍微久一点但是一劳永逸。装完以后你的 Mac 已经具备了一个标准的开发环境不只是 OpenClaw以后你再装其他开源软件基本都能顺畅通过了。3. 从零跑通OpenClaw安装两种方式新手选第一种3.1 方法一用Homebrew一行命令安装如果你的 Homebrew 环境已经按照上面的步骤装好了那么安装 OpenClaw 就变成了非常简单的一件事先去 Homebrew 仓库搜一下有没有官方封装好的安装包。brew search openclaw如果搜到了openclaw这个包那么恭喜你直接一行命令就能装好brew install openclaw这个过程会自动下载程序本体和依赖模块你只需要等待。下载期间终端会滚动很多文字新手看到大量滚动输出容易心慌其实大可不必。你只需要看最后有没有出现BUILD SUCCESS或者Installation successful之类的字眼或者返回正常的命令行提示符那就是装好了。Homebrew 方式最大的好处是省心。以后想卸载一条brew uninstall openclaw就能清理干净不会留下乱七八糟的文件。我推荐新手优先用这种方式。但要注意一点如果brew search openclaw结果显示No formula or cask found说明官方仓库还没收录这个包这时候不要硬憋直接切到下面的第二种方式。3.2 方法二用Git克隆源码手动安装第二种方式是从开源代码仓库把 OpenClaw 的源码下载到本地然后手动安装。这个过程稍长但它让你看清了软件的真实来源心里更踏实。首先建一个专门放源码的目录命令如下mkdir -p ~/Projects cd ~/Projects git clone https://github.com/your-account/openclaw.git cd openclaw这里把仓库地址替换成你搜索到的 OpenClaw 官方仓库地址。克隆完成之后进入项目目录执行安装脚本./install.sh有些版本可能需要用 Python 的包管理工具安装那么执行pip3 install -r requirements.txt python3 setup.py install这一套组合拳打完OpenClaw 就会被安装到你的系统路径里。安装过程中如果看到权限不足的报错就在命令前面加上sudo意思是以管理员权限执行比如sudo python3 setup.py install。不过要提醒一句sudo会让系统向你索要密码并且这种方式执行程序的权限很高没事别乱用只在明确要求装到系统目录时才用。3.3 验证安装是否成功不管用哪种方法装完最后一定要验证一下在终端输入openclaw --version如果能看到一个版本号比如openclaw 0.x.x说明安装成功。如果提示command not found也不用太紧张通常是安装路径没有被系统环境变量识别。解决方案是把 OpenClaw 的安装目录加到环境变量里具体路径取决于你安装的方式一般在/usr/local/bin或/opt/homebrew/bin。可以先用which openclaw查一下它到底装到了哪接着把路径配置到 shell 配置文件里。我强烈建议你在这一步多花几分钟跑一次验证别急着往下配置。因为如果安装有问题这时候排查是最简单的。等配置完再报错你往往就分不清是安装问题还是配置问题了。4. 首次配置与真实运行让OpenClaw第一次干活4.1 创建配置文件OpenClaw 运行之前需要知道三件事调用哪个模型服务的接口、用什么密钥去认证、把日志写到哪个地方。这些信息都放在一个叫配置文件的地方位置一般在你的用户主目录下文件名是.openclaw/config.json。如果这个文件不存在你可以手动创建。在终端执行mkdir -p ~/.openclaw touch ~/.openclaw/config.json然后你用访达打开这个位置用文本编辑打开这个空文件或者直接用终端里的编辑器都行。新手我建议先用图形界面编辑比较直观。4.2 填入API密钥和模型参数用文本编辑器打开config.json之后把它改成下面这个样子{ provider: your-provider-name, api_key: sk-xxxxxxxxxxxxxxxxxxxxx, model: default-model-name, log_level: info, log_file: /tmp/openclaw.log }这里有几个字段要解释一下provider填你注册的那个模型服务商的标识名这个标识名具体怎么写去 OpenClaw 的官方文档里查一下一般会有列出支持的提供商。api_key就填你之前保存的那一长串密钥。model填你想用的模型名称比如某服务商在文档里公布的默认模型ID。如果你不确定就留default-model-name对应的值很多服务商都有默认模型。log_level建议填info因为新手调试的时候需要看到尽量多的日志。log_file指定日志文件路径这样即使终端关了报错信息也有迹可循。这里有个很容易让人困惑的点为什么不是填服务商的网站地址因为 OpenClaw 作为一个框架已经内置了国内外各大主流模型服务商的对接代码不需要你手动填接口地址你只需要在配置里指定用哪家它自己就会找到对应的接口。这种设计对新手非常友好但也意味着你要确保填写的provider名字和官方文档完全一致哪怕大小写不一样都会导致连接失败。4.3 用内置检查命令验证配置配置文件填好之后先别急着跑任务很多失败都发生在这一步。OpenClaw 通常会提供一个命令来检查配置是否有效你试试openclaw doctor或者openclaw config test这条命令会读取你的配置文件尝试用你的密钥向服务器发一个极小的请求然后汇报是否成功。如果输出里出现了configuration ok或者connection successful一类的字眼说明配置通过。如果报错多半是密钥复制多了空格、provider 名字写错、或者模型名不对。处理办法也很简单仔细对一遍配置文件的每一个字符。4.4 跑一个简单的任务试试真章配置通过之后就可以开始真正的体验了。执行openclaw run 帮我整理一下最近三年AI代理框架的发展脉络输出300字左右的重点摘要。这时候你会看到 OpenClaw 开始接管任务它会去调用模型服务然后根据返回逐步生成内容。整个过程中终端会持续输出日志可能会显示类似calling model...、received response...这样的信息。首次运行通常会稍慢因为它需要加载一些模型参数和初始化工作目录但一般不会超过一两分钟。跑完之后你在终端里就能看到结果。你可以把指令改得更具体比如让它搜索信息、总结要点、生成表格。但要记住OpenClaw 的能力边界受限于你配置的模型能力和它内置的工具集不是任何指令都能完美执行。这一点用起来心里有数就好。4.5 日志文件怎么看如果运行过程中出了问题日志就是破案的关键。打开配置文件里填写的那个日志文件路径比如/tmp/openclaw.log用文本编辑器打开它你会看到一条条的日志记录。新手最需要关注的是带有ERROR或者WARN字样的行在这些行附近通常会有更详细的错误原因描述比如invalid api key、timeout、model not found。刚开始跑通的头几天我建议你养成每次运行完都翻一眼日志的习惯哪怕任务是成功的也看看有没有隐藏的警告。很多潜在的坑都是先从警告信息里露出苗头的。5. 新手必看的几个坑安装失败与运行报错速查5.1 输入openclaw却提示command not found这是最常见的报错之一。情况分两种第一种是根本没安装成功需要回到上一节检查安装流程第二种是你已经装好了但系统不知道去哪找这个程序。第二种的解决办法是把程序所在目录加入环境变量。你可以先用which openclaw来查如果它返回一个路径说明程序在只是 shell 不认如果没有返回路径说明程序不在了或者根本就没装上。如果是路径问题假设which openclaw查到的路径是/opt/homebrew/bin/openclaw那么你需要编辑自己的 shell 配置文件通常叫.zshrc加上下面这一行export PATH/opt/homebrew/bin:$PATH保存之后运行source ~/.zshrc使配置生效然后再试openclaw --version。这里值得注意的是如果你换了 M 系列芯片的 MacHomebrew 的安装路径通常自带/opt/homebrew/bin配置文件默认没有加载所以这一步对很多人都是必做项。5.2 下载速度极慢或者一直卡住安装 OpenClaw 或者 Homebrew 的时候卡住绝大多数是网络下载慢。这种问题主要发生在从境外服务器拉取源码或二进制包时。解决办法就是之前提过的换用社区镜像源。不要觉得换源是件很高端的事其实就是修改一些下载地址把国外的源换成国内同步的源速度立刻就会上来。另外还有一种情况是终端窗口看起来像卡住了其实是在等你做选择。比如有些安装脚本会问你是不是真的要装到某个目录如果终端上出现了[y/n]这样的提示你要输入y回车它才继续。新手很容易盯着屏幕发呆不知道要输入东西。解决方法是卡住的时候先检查一下最后一行是不是在询问什么。5.3 安装过程中编译报错如果你选择的是源码安装方式可能会遇到编译报错。这类报错信息通常很长常见原因包括缺依赖头文件、Python 版本不对、磁盘空间不足。最简单的处理顺序是先把 Python 升级到正式支持的版本再检查磁盘空间最后再去搜索报错信息中的关键错误码。当你不知道怎么办的时候把报错里带error的那一行原封不动复制到搜索引擎里基本都能找到前人踩坑的解答。这不是什么羞耻的操作反而是最有效率的方式。5.4 配置成功但一运行就超时这种问题多半出在模型接口的连通性上。虽然你的密钥有效但请求超时了。超时的原因可能是模型服务的公共接口区域负载过高、本地网络无法稳定访问该服务、或者你填的模型名在实际请求时路径不对。你可以做的第一件事是重试有时过几分钟就好第二件事是检查日志里的具体超时时间点如果在高峰时段尽量避开高峰期运行第三件事是确认你选的模型有没有被 OpenClaw 明确支持有些新模型虽然服务商已经灰度发布但 OpenClaw 的适配还没跟上就会一直超时。5.5 API密钥无效或者额度不足运行时报invalid api key是最容易排查也最容易让人哭笑不得的错误。最容易犯的低级错误是复制密钥时把前面的空格也复制进去了或者密钥尾部多了一个换行符。你可以在配置文件的api_key字段两侧打个引号确认没有多余的空格。额度不足则是另一个问题登录模型服务商的后台看余额和消耗记录如果额度用完了就充值或者更换一个仍有额度的模型。我把这些常见问题的排查步骤整理成一个速查表方便你到时候查阅症状首选排查动作次选排查动作command not found用which openclaw确认程序位置修改环境变量并执行source ~/.zshrc下载卡住检查终端是否在等待输入更换社区镜像源后重试编译报错搜索错误信息中的error行升级运行环境并释放磁盘空间运行超时避开高峰时段重试确认模型名是否被官方支持密钥无效检查密钥是否有空格或换行登录后台检查额度与状态5.6 卸载之后重装的注意事项如果你折腾了半天还是不行决定卸载重装那么建议先备份自己的配置文件。卸载命令很简单如果是 Homebrew 装的执行brew uninstall openclaw如果手动装的执行rm -rf ~/Projects/openclaw然后把配置文件也删掉。重装之前最好把系统的缓存清一清比如重启一次电脑。这样重装的时候很多之前残留的环境变量和临时文件不会干扰你。很多时候卸载后重启再装这一招能治好一半的疑难杂症。6. 把OpenClaw用顺手的三个小技巧6.1 设置一个常用别名告别敲长命令OpenClaw 的命令本身不短每跑一个新任务都要敲openclaw run 任务描述日积月累也是挺烦的。你可以在 shell 配置里加一个别名简化成几个字母。比如编辑.zshrc在末尾加上alias ocopenclaw run保存后执行source ~/.zshrc之后输入oc 帮我写个周报和原来那串长命令效果完全相同。我自己就经常用这个别名。任务跑完还能少敲一半键盘特别对于一天要跑几十次临时任务的人来说省下来的时间可不少。6.2 掌握正确的更新姿势OpenClaw 这个项目更新频率不低新功能和模型适配经常在迭代。用 Homebrew 装的更新很简单brew update brew upgrade openclaw源码方式装的进入源码目录然后cd ~/Projects/openclaw git pull ./install.sh但更新之前我要给你提个醒先去看一眼项目的更新日志或者发布说明如果发布说明里提到配置项有破坏性变更那你要做好修改配置文件的准备。更新完以后记得第一时间跑openclaw doctor验证一下配置是否兼容。我就有一次手痒更新到最新版结果模型配置字段名字变了所有任务直接报错那叫一个狼狈。6.3 把配置备份成模板少走弯路配置文件写好后建议你把它复制一份另存为模板比如config.backup.json。以后重装系统、换新电脑直接把这个模板拷过去改一下密钥就能用不需要重新去查文档。密钥这种东西最好单独存在一个文件夹里做一个key.txt但注意这个文件别放到会被同步网盘同步的位置防止泄露。还有一个进阶习惯如果你在不同场景要用不同的参数比如日常写作用一个模型复杂推理用另一个模型你可以保存多个配置文件运行时通过参数指定。具体怎么做看 OpenClaw 的文件文档这里不多展开。新手阶段先把一个配置用好跑通两三个任务再研究这些玩法也不迟。最后再分享一个小感受。我第一次把 OpenClaw 跑起来的时候其实没有想象中那种黑科技解放生产力的震撼反而是一种哦原来命令行软件是这样工作的的踏实感。装好它跟着日志看它一步步执行任务你对 AI 工具的理解会比只点网页版深很多。把这套基础打牢以后不管社区里冒出什么新的命令行 AI 工具你都不会再怕了。