开头我一直觉得本地化部署AI工具这件事最磨人的不是技术本身而是那些零零碎碎的环境坑。OpenClaw这个开源AI Agent项目我在Windows、Mac、Linux三台机器上前后折腾了快两个星期把从安装到配置再到调用的路完整走了一遍中间踩的坑很多是官方文档里根本不会写的。这篇文章就是我把整个部署过程重新梳理后的保姆级教程从零开始带你跑通OpenClaw三平台部署所有我踩过的坑都清清楚楚标出来。OpenClaw本质上是开源的AI Agent方案你可以把它理解成一个能操作电脑的AI助手给它一个任务它能自己调用工具、查资料、写代码、跑命令、操作浏览器定位上跟Manus这类产品类似但它是开源且可以完全本地部署的。这意味着你的数据、配置、模型调用都可以掌握在自己手里适合对数据隐私有要求、想深度定制Agent能力的个人开发者和小团队。不管你是Windows用户、Mac用户还是Linux服务器使用者这篇文章都会覆盖到。我会把每个平台特有的坑单独拎出来讲也会把通用的模型接入、Skill配置、手机端部署一并说清楚。如果你准备动手部署OpenClaw直接照着做就行。1. 部署前必须想明白的三件事1.1 OpenClaw到底是个什么东西很多人第一眼看到OpenClaw这个名字会以为是一个单一的程序实际上它是一个典型的客户端-服务端架构项目由好几个组件协作运行。最核心的是Clawdbot运行时负责调度Agent的思考循环和工具调用然后是一层API服务对外暴露接口方便你用Web界面、命令行或手机App来发起任务。此外还有一个Skill系统相当于给Agent预装各种能力包比如操作浏览器、解析文档、执行Shell命令等后面我会详细讲怎么配置Skill。理解这个架构很重要因为它直接决定你在三平台部署时不同的坑出现的位置。举个例子Windows上最容易出问题的是运行时的原生依赖编译Mac上最容易出问题的是Node.js的CPU架构不匹配而Linux上则是系统库缺失。这些问题虽然表现各不相同但根子都在于这个项目并非一个纯Java或纯Python的跨平台应用而是依赖了大量原生模块每个平台的编译环境稍有差异就会报出各种匪夷所思的错误。另外一个需要明确的概念是OpenClaw本身不内置大模型它只是一个大脑的载体真正的智能来自你接入的模型。官方支持通过API Key接入云端的模型服务也可以接入本地通过Ollama部署的开源模型比如DeepSeek、Qwen、Llama这一类的。本地部署大模型加OpenClaw的组合是目前最受关注的玩法算力在自己机器上跑数据不出内网断网了也照样能用。1.2 三平台方案选型原生安装还是Docker我查了不少社区里的部署帖发现大家在部署方式上大致分成两派一派是原生安装另一派是用Docker。我自己的实际感受是如果只是想在个人电脑上跑起来体验一下原生安装更直接也更容易排查问题因为你所有的依赖都是明晃晃装在系统里的出了错一眼就能看到是哪个环节挂的。而如果你要部署到服务器上做长期服务或者希望和团队共享一个Agent服务那Docker的隔离性和可移植性优势就很明显了环境打包后到哪都能跑不会因为服务器系统版本不同而炸掉。我在三个平台上的最终选择是Windows和macOS上用原生安装Linux服务器上用Docker。这个选择不是拍脑袋定的而是踩完坑之后的理性判断。Windows和Mac都是个人桌面环境装Docker Desktop本身就自带一堆资源占用问题在虚拟机里跑OpenClaw再去连宿主机上的Ollama网络配置又是一个坑。而Linux服务器本来就干净Docker装上去很顺滑代理服务需要的端口映射也简单所以Linux走Docker化反而省心。这篇文章的实操部分我会按这个思路来写但原生安装的步骤同样适用于想用Docker之外方案的人原理是一致的。1.3 环境依赖检查清单正式动手之前我建议你花五分钟把环境检查一遍别等到安装到一半才去补依赖。以下是我在三个平台上都验证过的依赖清单Git用来拉取仓库代码Windows和macOS需要手动装Linux一般自带。Node.js 20或更高版本OpenClaw的运行时和服务端都是基于Node.js的版本太老会直接跑不起来。Python 3.10以上部分Skill和工具脚本依赖Python解释器特别是文档解析、爬虫相关的模块。FFmpeg这个很多人会漏掉OpenClaw处理音视频任务时要调用FFmpeg转码没有它某些Skill会静默失败。Docker仅Linux服务器部署需要桌面端可选。一个模型API的访问途径要么注册云端的API服务拿到Key要么在本地装好Ollama并提前拉好模型。特别提醒一下Node.js建议用官方安装包或nvm安装不要用系统自带的旧版本。我在Windows上第一次部署就是因为系统里残留了一个老版本Node导致依赖安装时总是报语法错误排查了整整一个晚上才发现是版本问题。另外所有路径尽量不要带中文和空格这个坑在Windows上尤其致命我后面详细说。2. Windows平台部署坑最多但能跑通2.1 安装步骤与依赖处理Windows上的部署过程我用最简单的方式描述就是先把工具链补齐再拉代码装依赖最后配置模型跑起来。工具链这块我推荐用winget命令来装比手动去官网下载快得多在PowerShell里分别执行安装Git、Node.js 20、Python和FFmpeg的命令一条条装完。装完后务必重开一个终端窗口让环境变量生效然后确认一下版本。拉取OpenClaw仓库代码时千万注意目录路径。我一开始图省事直接放在了桌面下的中文文件夹里结果npm install阶段一堆原生模块编译失败报错信息写的都是node-gyp相关的错误但实际上根源是路径里的中文字符导致编译脚本解析出错。后来把项目克隆到D盘根目录下的英文路径一次就过了。这一步的经验是项目路径越简单越好C盘或D盘根目录下的纯英文文件夹是最安全的选择。依赖安装建议直接用npm install如果网络状况不理想导致超时可以设置镜像源再重试。装完依赖后项目里通常会有配置文件模板比如.env.example或者config.example.yaml复制一份出来命名为正式配置文件然后编辑模型接入信息这里我先按下不表第五章专门讲配置。配置文件准备好后启动命令一般是npm run start或者npm run dev第一次启动时OpenClaw会引导你完成初始化设置按提示操作就可以了。2.2 Windows独有的几个坑Windows可以说是OpenClaw部署的困难副本我数了一下自己踩过的坑至少有五个是Windows平台独有的。第一个是PowerShell执行策略默认情况下PowerShell不允许运行脚本npm命令本身没问题但某些模块的postinstall脚本会被系统拦截报错信息像乱码一样实际上只需要以管理员身份运行一次命令来更改执行策略即可。第二个坑是Windows Defender的实时保护。OpenClaw的Skill系统里有一些自动化脚本会被Defender误判为可疑文件直接隔离掉然后你的Skill就会莫名其妙消失。解决方法是把项目目录加入Defender的排除列表。这个操作我没有在官方文档里看到但从实际体验来看不加排除列表的话Skill功能时好时坏非常折磨人。第三个坑是ffmpeg的环境变量。虽然你单独下载了ffmpeg并解压到了某个文件夹但OpenClaw默认是在PATH里找ffmpeg的如果你没有把bin目录加进系统环境变量音视频类的任务就会报ffmpeg not found。注意加完环境变量后要重启终端不然依然找不到。第四个坑是Windows下原生模块编译需要Visual Studio Build Tools。虽然我之前提过路径问题是编译失败的主要原因但即便路径正确部分模块比如某些涉及文件系统监控的库还是需要C编译环境。如果报错日志里出现node-gyp和MSBuild字样基本就是缺这个。安装Visual Studio Build Tools勾选C桌面开发组件后重试问题就能解决。第五个坑藏在Windows的换行符里。用Git拉取代码时如果autocrlf设置为true某些脚本文件会被自动改成Windows的CRLF换行执行时会报出奇怪的语法错误。解决方法是关掉自动换行转换也就是将core.autocrlf设为false拉完代码后重装一遍依赖。这五个坑全部绕过去之后Windows上的OpenClaw就能稳定运行了。2.3 Windows Companion配置要点Windows平台上还有一个特色功能叫Windows Companion简单说就是让OpenClaw能够深度控制Windows系统层面的操作比如模拟鼠标键盘、读取屏幕内容、管理应用程序窗口。很多人在社区里问OpenClaw Windows Companion怎么配置我补充一下这里的要点。Companion的定位是独立的后台辅助进程需要单独启动然后在OpenClaw的主配置里把通信地址填上。安装的时候Companion需要以管理员权限安装否则无法注册系统级的自动化能力。启动后它会在系统托盘显示图标正常运行时你会在配置界面的设备列表里看到本机的状态变成在线。这个过程中最容易出的问题有两个一个是防火墙拦截了Companion的本地通信端口需要手动放行另一个是Companion版本和OpenClaw主程序版本不一致导致连接失败升级的时候要一起升。Windows上如果你能完整跑通OpenClaw加Companion那这个Agent基本可以当半个机器人助手来用了自动化办公场景的体验会提升一个档次。3. macOS平台部署Apple Silicon的坑3.1 Homebrew安装与依赖准备macOS上的部署过程通常比Windows顺滑一些但如果你是Apple Silicon芯片的机器还是会遇到一个绕不开的架构问题。OpenClaw的依赖里有部分原生模块是x86编译的在ARM架构下需要转译或重新编译如果直接用系统的Node来跑经常会报出架构不匹配的错误。我把Mac上的部署路径这样规划的先用Homebrew把Git、Node.js、Python、FFmpeg装齐这一步跟Windows的思路一致只是包管理器换成了brew。终端里分别执行安装命令即可。Homebrew很强大的一点是它自动处理依赖关系遇到编译工具链缺失会自动装上。装完同样确认版本然后将项目克隆到用户目录下的英文路径例如~/Projects/clawdbot。在Apple Silicon上有一个很实用的技巧就是如果你的机器上安装了Rosetta 2Node.js可以用x86版本运行对某些依赖的兼容性反而更好。不过我不太推荐一开始就折腾这个方向更稳妥的做法是先用brew安装的ARM版本Node跑一遍npm install如果没报错就直接用如果报错再考虑切到x86环境。实际部署过程中我身边的开发者更多是选择在Mac上直接用Docker跑OpenClaw来规避原生依赖问题但我个人觉得原生跑也不难只要依赖版本别乱更新就行。3.2 权限弹窗与系统安全限制macOS上踩坑的大头不在依赖而在系统安全机制。第一次启动OpenClaw时macOS会弹出多个权限请求包括访问文件夹、接收网络连接、控制系统UI等。很多人以为直接点允许就行了但OpenClaw毕竟是个命令行工具它跑在终端里系统不知道该怎么赋予权限所以你会发现明明在终端里全局搜索都开了它还是提示没有权限。我的处理方式是在系统设置里找到隐私与安全性把终端或者你用的IDE集成终端加入权限白名单尤其是文件和文件夹、屏幕录制、辅助功能这三个分类。屏幕录制权限是Companion类功能必须的没有它Agent就看不到屏幕内容。辅助功能权限是模拟键鼠操作必须的没有它就无法控制其他应用。这俩权限不给Agent的能力直接砍半。还有一个跟Windows上类似的问题是macOS的Gatekeeper会对从GitHub下载的未知开发者应用做拦截。虽然你运行的是一个Node.js项目不会触发这个机制但如果后续安装了一些辅助工具比如独立的Companion组件Gatekeeper就可能弹出警告。如果遇到无法打开因为无法验证开发者的提示需要到系统设置里手动允许。这些操作都做完macOS上跑OpenClaw的体验就非常丝滑了在日常开发机上连着跑几天不太会遇到问题。4. Linux服务器部署生产环境首选4.1 Ubuntu系统上的纯净部署流程Linux服务器是我最推荐的OpenClaw长期运行环境因为它干净、稳定、资源利用率高。这里以Ubuntu 22.04为例梳理整个流程其他发行版原理相同只是包管理器命令略有差异。VPS环境我建议直接走Docker路线隔离性好升级也方便但这节我会把原生安装和Docker两条路都写出来。原生安装的方式很简单先通过apt把curl、git、build-essential这些基础工具装上然后用NodeSource脚本安装Node.js 20再用apt装Python和FFmpeg。一切都按标准流程来不做多余操作。接着克隆代码、安装依赖、配置模型信息然后用npm run start启动。原生安装的好处是排错直观坏处是如果服务器上同时跑着多个服务依赖版本可能互相冲突到时候维护成本会上升。我更推荐在Linux上用Docker Compose来部署配置很容易组织。大致流程是先安装Docker引擎和Compose插件然后写一个compose文件里面定义OpenClaw服务挂载配置目录和Skill目录映射需要的端口。如果你还要在服务器上跑Ollama提供本地模型推理就把Ollama也作为同一个compose文件里的一个服务这样两个容器在同一个Docker网络里可以直接通过服务名互访非常干净。我第一次把Ollama和OpenClaw放在同一个compose里的原因就是为了省掉配置主机IP的麻烦实测下来稳定得很。4.2 让OpenClaw后台常驻运行Linux上一旦要用OpenClaw做长期服务就不能只是开一个终端挂着因为SSH一断开进程就没了。我在服务器上试过三种常驻方案nohup、tmux、systemd。nohup最简单一条命令就能让进程后台跑日志重定向到文件但进程崩溃了不会自动重启。tmux是交互式终端的思路开一个会话挂着掉线了能重新接回来但需要手动管理会话不够自动化。最终我选的是systemd服务方案。把启动命令写成一个service文件放到系统目录里然后通过systemctl enable开启开机自启systemctl start启动服务。这样OpenClaw就真正变成系统级服务了崩溃了systemd会自动拉起日志统一收在journald里查问题用一条命令就能看全部日志。网上很多人直接用Docker跑的时候干脆加了restartalways策略也能达到同样的效果这算是容器化方案的一个天然优势。无论用哪种方式常驻我都建议给OpenClaw建一个独立的系统用户别拿root身份跑服务。虽然配置上会多几步但安全收益是实打实的。尤其是Agent的Skill系统可以执行Shell命令一旦被恶意利用root权限造成的破坏是不可逆的。这一点在Linux部署时尤其要重视毕竟服务器干的是正经生产事。5. 模型接入与Skill体系配置5.1 API接入与本地Ollama模型OpenClaw的模型接入层设计得比较灵活你可以在配置里指定使用云端API还是本地推理引擎。走API这条路最省事只需要在配置文件里填上服务商地址和Key就行适合不想折腾硬件、追求快速体验的用户。我测试下来用云端API做复杂任务时的响应质量和速度都很好但代价是每一轮对话和工具调用都会产生费用如果你让Agent跑一个多步骤的长任务账单涨得会特别快。本地模型的路子我首推Ollama因为部署非常简单跨平台支持做得也好。你先在机器上装好Ollama然后拉取一个模型在OpenClaw的配置里把模型供应商切换成Ollama填上Ollama服务的地址和模型名称就能直接跑了。需要说明的是OpenClaw本身不处理模型推理它只是把任务拆解后把指令发给模型拿到结果再决定下一步动作所以模型能力直接决定Agent的实际表现。我自己的测试感受是如果是写代码、查资料这类偏推理的任务用云端大模型的效果明显更好如果只是做定时任务、网页操作、数据整理这类执行型工作本地模型足够胜任而且响应速度还要更快因为没有网络延迟。另外DeepSeek系列模型因为开源且中文能力强成为很多国内开发者在本地部署时的首选模型热词里也频繁出现deepseek部署本地部署deepseek的搜索说明这条路是主流的玩法。5.2 Skill系统配置示例Skill是OpenClaw很核心的扩展机制每一个Skill相当于给Agent装了一个专业工具包。官方自带了一些基础Skill比如浏览器操作、终端执行、文件管理等但如果你想让它做更垂直的事情就需要自己配置Skill了。配置Skill其实不复杂每种Skill对应一个文件夹里面放着描述文件、脚本和依赖清单。你只需要把写好的Skill文件夹放到项目的skills目录下然后在配置文件里启用它OpenClaw下一次启动时就会自动加载。举个例子我写了一个定时巡检服务器磁盘的Skill描述文件里写清楚触发条件和执行逻辑执行脚本用Python写里面调用了df命令来获取磁盘使用率超过阈值就发通知。整个过程不到两小时就搞定比单独写一个定时监控脚本还要直观。Skill系统让我觉得最惊艳的一点是它真的能做到即插即用。你不需要修改OpenClaw的任何核心代码只需要满足Skill描述文件里的依赖条件这个能力就会被Agent自动识别和使用而且Agent还会根据描述文件来判断什么时候该调用这个Skill。社区的Skill生态也已经起来了热词里出现openclaw skill搜索量不算低很多开发者都在分享自己写的Skill包拿过来放到目录里就能用发布方式有点像GitHub上的开源项目民间大家也把这套机制类比成早年IDE的插件市场。5.3 安卓Termux部署补充很多人在手机上也想跑OpenClaw这个场景确实存在。社区里最常提到的方式是用Termux它是一个安卓上的终端模拟器可以在手机上提供一个类似Linux的环境。热词里How to install OpenClaw on Android via Termux这个搜索也印证了大家的兴趣这里我简单补充几句。Termux上需要先安装Node.js和Git然后用命令行克隆OpenClaw代码、装依赖、配置模型地址。由于手机性能和系统限制我强烈建议手机端只做Agent任务的发起端和查看端把实际执行放在电脑或服务器上这样体验会流畅很多。Termux官方源里能装的Node版本可能偏旧如果装完依赖报错需要先升级Node再继续这个坑我在测试时遇到过。手机端的网络环境和桌面端也不同要保证OpenClaw服务端的接口可以被手机访问到最简单的方式是用Tailscale这类组网工具把设备拉进同一个虚拟局域网这样在外网也能安全地访问家里的服务配置起来不复杂安全性也有保障。6. 高频问题与排查速查表6.1 部署期典型报错与解法这节我把自己实际部署过程中遇到的报错和排查思路统一整理成速查表方便你遇到问题时直接对号入座报错现象发生阶段常见原因解决方案node-gyp编译失败npm install缺C编译工具链或路径含中文空格安装Build Tools项目移到纯英文路径ffmpeg not found启动后执行音视频任务ffmpeg不在PATH中安装ffmpeg并加入系统PATH重启终端Module version mismatch启动时Node版本与原生模块编译时不一致统一Node版本重装依赖EACCES权限拒绝启动时Linux下无权限写日志或状态文件用非root用户并赋予项目目录写权限端口被占用启动时默认端口被其他服务占用修改配置文件端口号或停掉冲突服务提示缺少配置文件首次启动没有从模板生成配置文件复制模板文件并填好必填项Skill列表为空启动后Skill文件被安全软件隔离或目录挂载错误检查目录路径加入防病毒白名单每一个报错对应的排查路径其实都遵循同一个套路先看日志再看依赖再查环境变量。OpenClaw的日志信息其实写得相当直白很多人第一步就慌乱忽略了日志里已经标出来的关键提示。学会看日志百分之八十的问题都能自己解决。6.2 运行期故障排查实录部署成功只是第一步运行期的故障往往更隐蔽。我在长期运行OpenClaw的过程中遇到过三个比较典型的问题这里单独拿出来讲。第一个是Agent执行任务到一半突然中断没有任何报错。排查后发现是模型服务过载导致响应超时OpenClaw默认的超时时间比较短本地小模型推理速度跟不上就触发了中断保护。解决方案是在配置里调大超时时间或者换更强的推理硬件。这是最典型的本地部署大模型和Agent框架协同时的性能匹配问题值得重点关注。第二个是Skill脚本执行成功但结果没被Agent正确解析。这个问题的根源在于Skill描述文件里没有写清楚输出格式Agent拿到自由格式的文文本无法提取关键信息。解决方案是在描述文件里明确要求脚本输出固定格式比如每行一个字段、用管道符分隔。这个经验告诉我Skill配置不能只关注脚本本身输出契约同样重要。第三个是Companion或手机端经常掉线。排查下来发现是局域网IP变动导致的服务地址失效。家里路由器重启后设备IP变了之前的连接全部断了。解决方法是给设备配置静态IP或者用组网工具解决跨网络访问问题让客户端通过固定地址访问OpenClaw服务就不会因为IP漂移而掉线了。6.3 卸载与重装时要注意什么最后补充一个热词里出现频率不低的问题怎么卸载OpenClaw。虽然是反向操作但确实很多人装完想清理或者重装时卡住了。Windows上卸载相对简单项目目录和控制面板里的卸载项处理干净即可但别忘了把系统环境变量里手动加过的ffmpeg路径一并删掉。macOS上用brew装过的依赖可以通过brew uninstall清理用户目录下的配置文件单独删。Linux下如果走了systemd服务要先停服务再删文件。重装场景我遇到的最多的问题是旧配置里残留的Key和端口信息导致新实例启动失败。所以无论哪个平台卸载或重装前第一步都应该是备份配置目录第二步彻底清理环境变量和临时文件第三步再动依赖和代码。我个人的习惯是把OpenClaw的配置目录整个打压缩包存起来重装后直接恢复省去重新配置模型和Skill的功夫。这段时间在三平台反复折腾OpenClaw最大的收获就是彻底搞懂了这类Agent框架的部署逻辑先备环境、再跑代码、然后调模型、最后折腾扩展。每一步的坑其实都大同小异根子还是那些原生依赖、路径、权限、版本的老问题。如果你照着这篇文章部署时仍然遇到我写漏的坑建议先冷静看日志确认好报错关键词再搜方案大部分问题都能用这个笨办法解决。等把OpenClaw真正跑起来、接上你自己调好的模型你会觉得前面所有折腾都值回票价。 
长河君 · 2026/10/7 19:27:25 · 阅读 1.2k OpenClaw三平台部署全攻略：Windows/macOS/Linux踩坑实录与Agent配置指南
开头我一直觉得本地化部署AI工具这件事最磨人的不是技术本身而是那些零零碎碎的环境坑。OpenClaw这个开源AI Agent项目我在Windows、Mac、Linux三台机器上前后折腾了快两个星期把从安装到配置再到调用的路完整走了一遍中间踩的坑很多是官方文档里根本不会写的。这篇文章就是我把整个部署过程重新梳理后的保姆级教程从零开始带你跑通OpenClaw三平台部署所有我踩过的坑都清清楚楚标出来。OpenClaw本质上是开源的AI Agent方案你可以把它理解成一个能操作电脑的AI助手给它一个任务它能自己调用工具、查资料、写代码、跑命令、操作浏览器定位上跟Manus这类产品类似但它是开源且可以完全本地部署的。这意味着你的数据、配置、模型调用都可以掌握在自己手里适合对数据隐私有要求、想深度定制Agent能力的个人开发者和小团队。不管你是Windows用户、Mac用户还是Linux服务器使用者这篇文章都会覆盖到。我会把每个平台特有的坑单独拎出来讲也会把通用的模型接入、Skill配置、手机端部署一并说清楚。如果你准备动手部署OpenClaw直接照着做就行。1. 部署前必须想明白的三件事1.1 OpenClaw到底是个什么东西很多人第一眼看到OpenClaw这个名字会以为是一个单一的程序实际上它是一个典型的客户端-服务端架构项目由好几个组件协作运行。最核心的是Clawdbot运行时负责调度Agent的思考循环和工具调用然后是一层API服务对外暴露接口方便你用Web界面、命令行或手机App来发起任务。此外还有一个Skill系统相当于给Agent预装各种能力包比如操作浏览器、解析文档、执行Shell命令等后面我会详细讲怎么配置Skill。理解这个架构很重要因为它直接决定你在三平台部署时不同的坑出现的位置。举个例子Windows上最容易出问题的是运行时的原生依赖编译Mac上最容易出问题的是Node.js的CPU架构不匹配而Linux上则是系统库缺失。这些问题虽然表现各不相同但根子都在于这个项目并非一个纯Java或纯Python的跨平台应用而是依赖了大量原生模块每个平台的编译环境稍有差异就会报出各种匪夷所思的错误。另外一个需要明确的概念是OpenClaw本身不内置大模型它只是一个大脑的载体真正的智能来自你接入的模型。官方支持通过API Key接入云端的模型服务也可以接入本地通过Ollama部署的开源模型比如DeepSeek、Qwen、Llama这一类的。本地部署大模型加OpenClaw的组合是目前最受关注的玩法算力在自己机器上跑数据不出内网断网了也照样能用。1.2 三平台方案选型原生安装还是Docker我查了不少社区里的部署帖发现大家在部署方式上大致分成两派一派是原生安装另一派是用Docker。我自己的实际感受是如果只是想在个人电脑上跑起来体验一下原生安装更直接也更容易排查问题因为你所有的依赖都是明晃晃装在系统里的出了错一眼就能看到是哪个环节挂的。而如果你要部署到服务器上做长期服务或者希望和团队共享一个Agent服务那Docker的隔离性和可移植性优势就很明显了环境打包后到哪都能跑不会因为服务器系统版本不同而炸掉。我在三个平台上的最终选择是Windows和macOS上用原生安装Linux服务器上用Docker。这个选择不是拍脑袋定的而是踩完坑之后的理性判断。Windows和Mac都是个人桌面环境装Docker Desktop本身就自带一堆资源占用问题在虚拟机里跑OpenClaw再去连宿主机上的Ollama网络配置又是一个坑。而Linux服务器本来就干净Docker装上去很顺滑代理服务需要的端口映射也简单所以Linux走Docker化反而省心。这篇文章的实操部分我会按这个思路来写但原生安装的步骤同样适用于想用Docker之外方案的人原理是一致的。1.3 环境依赖检查清单正式动手之前我建议你花五分钟把环境检查一遍别等到安装到一半才去补依赖。以下是我在三个平台上都验证过的依赖清单Git用来拉取仓库代码Windows和macOS需要手动装Linux一般自带。Node.js 20或更高版本OpenClaw的运行时和服务端都是基于Node.js的版本太老会直接跑不起来。Python 3.10以上部分Skill和工具脚本依赖Python解释器特别是文档解析、爬虫相关的模块。FFmpeg这个很多人会漏掉OpenClaw处理音视频任务时要调用FFmpeg转码没有它某些Skill会静默失败。Docker仅Linux服务器部署需要桌面端可选。一个模型API的访问途径要么注册云端的API服务拿到Key要么在本地装好Ollama并提前拉好模型。特别提醒一下Node.js建议用官方安装包或nvm安装不要用系统自带的旧版本。我在Windows上第一次部署就是因为系统里残留了一个老版本Node导致依赖安装时总是报语法错误排查了整整一个晚上才发现是版本问题。另外所有路径尽量不要带中文和空格这个坑在Windows上尤其致命我后面详细说。2. Windows平台部署坑最多但能跑通2.1 安装步骤与依赖处理Windows上的部署过程我用最简单的方式描述就是先把工具链补齐再拉代码装依赖最后配置模型跑起来。工具链这块我推荐用winget命令来装比手动去官网下载快得多在PowerShell里分别执行安装Git、Node.js 20、Python和FFmpeg的命令一条条装完。装完后务必重开一个终端窗口让环境变量生效然后确认一下版本。拉取OpenClaw仓库代码时千万注意目录路径。我一开始图省事直接放在了桌面下的中文文件夹里结果npm install阶段一堆原生模块编译失败报错信息写的都是node-gyp相关的错误但实际上根源是路径里的中文字符导致编译脚本解析出错。后来把项目克隆到D盘根目录下的英文路径一次就过了。这一步的经验是项目路径越简单越好C盘或D盘根目录下的纯英文文件夹是最安全的选择。依赖安装建议直接用npm install如果网络状况不理想导致超时可以设置镜像源再重试。装完依赖后项目里通常会有配置文件模板比如.env.example或者config.example.yaml复制一份出来命名为正式配置文件然后编辑模型接入信息这里我先按下不表第五章专门讲配置。配置文件准备好后启动命令一般是npm run start或者npm run dev第一次启动时OpenClaw会引导你完成初始化设置按提示操作就可以了。2.2 Windows独有的几个坑Windows可以说是OpenClaw部署的困难副本我数了一下自己踩过的坑至少有五个是Windows平台独有的。第一个是PowerShell执行策略默认情况下PowerShell不允许运行脚本npm命令本身没问题但某些模块的postinstall脚本会被系统拦截报错信息像乱码一样实际上只需要以管理员身份运行一次命令来更改执行策略即可。第二个坑是Windows Defender的实时保护。OpenClaw的Skill系统里有一些自动化脚本会被Defender误判为可疑文件直接隔离掉然后你的Skill就会莫名其妙消失。解决方法是把项目目录加入Defender的排除列表。这个操作我没有在官方文档里看到但从实际体验来看不加排除列表的话Skill功能时好时坏非常折磨人。第三个坑是ffmpeg的环境变量。虽然你单独下载了ffmpeg并解压到了某个文件夹但OpenClaw默认是在PATH里找ffmpeg的如果你没有把bin目录加进系统环境变量音视频类的任务就会报ffmpeg not found。注意加完环境变量后要重启终端不然依然找不到。第四个坑是Windows下原生模块编译需要Visual Studio Build Tools。虽然我之前提过路径问题是编译失败的主要原因但即便路径正确部分模块比如某些涉及文件系统监控的库还是需要C编译环境。如果报错日志里出现node-gyp和MSBuild字样基本就是缺这个。安装Visual Studio Build Tools勾选C桌面开发组件后重试问题就能解决。第五个坑藏在Windows的换行符里。用Git拉取代码时如果autocrlf设置为true某些脚本文件会被自动改成Windows的CRLF换行执行时会报出奇怪的语法错误。解决方法是关掉自动换行转换也就是将core.autocrlf设为false拉完代码后重装一遍依赖。这五个坑全部绕过去之后Windows上的OpenClaw就能稳定运行了。2.3 Windows Companion配置要点Windows平台上还有一个特色功能叫Windows Companion简单说就是让OpenClaw能够深度控制Windows系统层面的操作比如模拟鼠标键盘、读取屏幕内容、管理应用程序窗口。很多人在社区里问OpenClaw Windows Companion怎么配置我补充一下这里的要点。Companion的定位是独立的后台辅助进程需要单独启动然后在OpenClaw的主配置里把通信地址填上。安装的时候Companion需要以管理员权限安装否则无法注册系统级的自动化能力。启动后它会在系统托盘显示图标正常运行时你会在配置界面的设备列表里看到本机的状态变成在线。这个过程中最容易出的问题有两个一个是防火墙拦截了Companion的本地通信端口需要手动放行另一个是Companion版本和OpenClaw主程序版本不一致导致连接失败升级的时候要一起升。Windows上如果你能完整跑通OpenClaw加Companion那这个Agent基本可以当半个机器人助手来用了自动化办公场景的体验会提升一个档次。3. macOS平台部署Apple Silicon的坑3.1 Homebrew安装与依赖准备macOS上的部署过程通常比Windows顺滑一些但如果你是Apple Silicon芯片的机器还是会遇到一个绕不开的架构问题。OpenClaw的依赖里有部分原生模块是x86编译的在ARM架构下需要转译或重新编译如果直接用系统的Node来跑经常会报出架构不匹配的错误。我把Mac上的部署路径这样规划的先用Homebrew把Git、Node.js、Python、FFmpeg装齐这一步跟Windows的思路一致只是包管理器换成了brew。终端里分别执行安装命令即可。Homebrew很强大的一点是它自动处理依赖关系遇到编译工具链缺失会自动装上。装完同样确认版本然后将项目克隆到用户目录下的英文路径例如~/Projects/clawdbot。在Apple Silicon上有一个很实用的技巧就是如果你的机器上安装了Rosetta 2Node.js可以用x86版本运行对某些依赖的兼容性反而更好。不过我不太推荐一开始就折腾这个方向更稳妥的做法是先用brew安装的ARM版本Node跑一遍npm install如果没报错就直接用如果报错再考虑切到x86环境。实际部署过程中我身边的开发者更多是选择在Mac上直接用Docker跑OpenClaw来规避原生依赖问题但我个人觉得原生跑也不难只要依赖版本别乱更新就行。3.2 权限弹窗与系统安全限制macOS上踩坑的大头不在依赖而在系统安全机制。第一次启动OpenClaw时macOS会弹出多个权限请求包括访问文件夹、接收网络连接、控制系统UI等。很多人以为直接点允许就行了但OpenClaw毕竟是个命令行工具它跑在终端里系统不知道该怎么赋予权限所以你会发现明明在终端里全局搜索都开了它还是提示没有权限。我的处理方式是在系统设置里找到隐私与安全性把终端或者你用的IDE集成终端加入权限白名单尤其是文件和文件夹、屏幕录制、辅助功能这三个分类。屏幕录制权限是Companion类功能必须的没有它Agent就看不到屏幕内容。辅助功能权限是模拟键鼠操作必须的没有它就无法控制其他应用。这俩权限不给Agent的能力直接砍半。还有一个跟Windows上类似的问题是macOS的Gatekeeper会对从GitHub下载的未知开发者应用做拦截。虽然你运行的是一个Node.js项目不会触发这个机制但如果后续安装了一些辅助工具比如独立的Companion组件Gatekeeper就可能弹出警告。如果遇到无法打开因为无法验证开发者的提示需要到系统设置里手动允许。这些操作都做完macOS上跑OpenClaw的体验就非常丝滑了在日常开发机上连着跑几天不太会遇到问题。4. Linux服务器部署生产环境首选4.1 Ubuntu系统上的纯净部署流程Linux服务器是我最推荐的OpenClaw长期运行环境因为它干净、稳定、资源利用率高。这里以Ubuntu 22.04为例梳理整个流程其他发行版原理相同只是包管理器命令略有差异。VPS环境我建议直接走Docker路线隔离性好升级也方便但这节我会把原生安装和Docker两条路都写出来。原生安装的方式很简单先通过apt把curl、git、build-essential这些基础工具装上然后用NodeSource脚本安装Node.js 20再用apt装Python和FFmpeg。一切都按标准流程来不做多余操作。接着克隆代码、安装依赖、配置模型信息然后用npm run start启动。原生安装的好处是排错直观坏处是如果服务器上同时跑着多个服务依赖版本可能互相冲突到时候维护成本会上升。我更推荐在Linux上用Docker Compose来部署配置很容易组织。大致流程是先安装Docker引擎和Compose插件然后写一个compose文件里面定义OpenClaw服务挂载配置目录和Skill目录映射需要的端口。如果你还要在服务器上跑Ollama提供本地模型推理就把Ollama也作为同一个compose文件里的一个服务这样两个容器在同一个Docker网络里可以直接通过服务名互访非常干净。我第一次把Ollama和OpenClaw放在同一个compose里的原因就是为了省掉配置主机IP的麻烦实测下来稳定得很。4.2 让OpenClaw后台常驻运行Linux上一旦要用OpenClaw做长期服务就不能只是开一个终端挂着因为SSH一断开进程就没了。我在服务器上试过三种常驻方案nohup、tmux、systemd。nohup最简单一条命令就能让进程后台跑日志重定向到文件但进程崩溃了不会自动重启。tmux是交互式终端的思路开一个会话挂着掉线了能重新接回来但需要手动管理会话不够自动化。最终我选的是systemd服务方案。把启动命令写成一个service文件放到系统目录里然后通过systemctl enable开启开机自启systemctl start启动服务。这样OpenClaw就真正变成系统级服务了崩溃了systemd会自动拉起日志统一收在journald里查问题用一条命令就能看全部日志。网上很多人直接用Docker跑的时候干脆加了restartalways策略也能达到同样的效果这算是容器化方案的一个天然优势。无论用哪种方式常驻我都建议给OpenClaw建一个独立的系统用户别拿root身份跑服务。虽然配置上会多几步但安全收益是实打实的。尤其是Agent的Skill系统可以执行Shell命令一旦被恶意利用root权限造成的破坏是不可逆的。这一点在Linux部署时尤其要重视毕竟服务器干的是正经生产事。5. 模型接入与Skill体系配置5.1 API接入与本地Ollama模型OpenClaw的模型接入层设计得比较灵活你可以在配置里指定使用云端API还是本地推理引擎。走API这条路最省事只需要在配置文件里填上服务商地址和Key就行适合不想折腾硬件、追求快速体验的用户。我测试下来用云端API做复杂任务时的响应质量和速度都很好但代价是每一轮对话和工具调用都会产生费用如果你让Agent跑一个多步骤的长任务账单涨得会特别快。本地模型的路子我首推Ollama因为部署非常简单跨平台支持做得也好。你先在机器上装好Ollama然后拉取一个模型在OpenClaw的配置里把模型供应商切换成Ollama填上Ollama服务的地址和模型名称就能直接跑了。需要说明的是OpenClaw本身不处理模型推理它只是把任务拆解后把指令发给模型拿到结果再决定下一步动作所以模型能力直接决定Agent的实际表现。我自己的测试感受是如果是写代码、查资料这类偏推理的任务用云端大模型的效果明显更好如果只是做定时任务、网页操作、数据整理这类执行型工作本地模型足够胜任而且响应速度还要更快因为没有网络延迟。另外DeepSeek系列模型因为开源且中文能力强成为很多国内开发者在本地部署时的首选模型热词里也频繁出现deepseek部署本地部署deepseek的搜索说明这条路是主流的玩法。5.2 Skill系统配置示例Skill是OpenClaw很核心的扩展机制每一个Skill相当于给Agent装了一个专业工具包。官方自带了一些基础Skill比如浏览器操作、终端执行、文件管理等但如果你想让它做更垂直的事情就需要自己配置Skill了。配置Skill其实不复杂每种Skill对应一个文件夹里面放着描述文件、脚本和依赖清单。你只需要把写好的Skill文件夹放到项目的skills目录下然后在配置文件里启用它OpenClaw下一次启动时就会自动加载。举个例子我写了一个定时巡检服务器磁盘的Skill描述文件里写清楚触发条件和执行逻辑执行脚本用Python写里面调用了df命令来获取磁盘使用率超过阈值就发通知。整个过程不到两小时就搞定比单独写一个定时监控脚本还要直观。Skill系统让我觉得最惊艳的一点是它真的能做到即插即用。你不需要修改OpenClaw的任何核心代码只需要满足Skill描述文件里的依赖条件这个能力就会被Agent自动识别和使用而且Agent还会根据描述文件来判断什么时候该调用这个Skill。社区的Skill生态也已经起来了热词里出现openclaw skill搜索量不算低很多开发者都在分享自己写的Skill包拿过来放到目录里就能用发布方式有点像GitHub上的开源项目民间大家也把这套机制类比成早年IDE的插件市场。5.3 安卓Termux部署补充很多人在手机上也想跑OpenClaw这个场景确实存在。社区里最常提到的方式是用Termux它是一个安卓上的终端模拟器可以在手机上提供一个类似Linux的环境。热词里How to install OpenClaw on Android via Termux这个搜索也印证了大家的兴趣这里我简单补充几句。Termux上需要先安装Node.js和Git然后用命令行克隆OpenClaw代码、装依赖、配置模型地址。由于手机性能和系统限制我强烈建议手机端只做Agent任务的发起端和查看端把实际执行放在电脑或服务器上这样体验会流畅很多。Termux官方源里能装的Node版本可能偏旧如果装完依赖报错需要先升级Node再继续这个坑我在测试时遇到过。手机端的网络环境和桌面端也不同要保证OpenClaw服务端的接口可以被手机访问到最简单的方式是用Tailscale这类组网工具把设备拉进同一个虚拟局域网这样在外网也能安全地访问家里的服务配置起来不复杂安全性也有保障。6. 高频问题与排查速查表6.1 部署期典型报错与解法这节我把自己实际部署过程中遇到的报错和排查思路统一整理成速查表方便你遇到问题时直接对号入座报错现象发生阶段常见原因解决方案node-gyp编译失败npm install缺C编译工具链或路径含中文空格安装Build Tools项目移到纯英文路径ffmpeg not found启动后执行音视频任务ffmpeg不在PATH中安装ffmpeg并加入系统PATH重启终端Module version mismatch启动时Node版本与原生模块编译时不一致统一Node版本重装依赖EACCES权限拒绝启动时Linux下无权限写日志或状态文件用非root用户并赋予项目目录写权限端口被占用启动时默认端口被其他服务占用修改配置文件端口号或停掉冲突服务提示缺少配置文件首次启动没有从模板生成配置文件复制模板文件并填好必填项Skill列表为空启动后Skill文件被安全软件隔离或目录挂载错误检查目录路径加入防病毒白名单每一个报错对应的排查路径其实都遵循同一个套路先看日志再看依赖再查环境变量。OpenClaw的日志信息其实写得相当直白很多人第一步就慌乱忽略了日志里已经标出来的关键提示。学会看日志百分之八十的问题都能自己解决。6.2 运行期故障排查实录部署成功只是第一步运行期的故障往往更隐蔽。我在长期运行OpenClaw的过程中遇到过三个比较典型的问题这里单独拿出来讲。第一个是Agent执行任务到一半突然中断没有任何报错。排查后发现是模型服务过载导致响应超时OpenClaw默认的超时时间比较短本地小模型推理速度跟不上就触发了中断保护。解决方案是在配置里调大超时时间或者换更强的推理硬件。这是最典型的本地部署大模型和Agent框架协同时的性能匹配问题值得重点关注。第二个是Skill脚本执行成功但结果没被Agent正确解析。这个问题的根源在于Skill描述文件里没有写清楚输出格式Agent拿到自由格式的文文本无法提取关键信息。解决方案是在描述文件里明确要求脚本输出固定格式比如每行一个字段、用管道符分隔。这个经验告诉我Skill配置不能只关注脚本本身输出契约同样重要。第三个是Companion或手机端经常掉线。排查下来发现是局域网IP变动导致的服务地址失效。家里路由器重启后设备IP变了之前的连接全部断了。解决方法是给设备配置静态IP或者用组网工具解决跨网络访问问题让客户端通过固定地址访问OpenClaw服务就不会因为IP漂移而掉线了。6.3 卸载与重装时要注意什么最后补充一个热词里出现频率不低的问题怎么卸载OpenClaw。虽然是反向操作但确实很多人装完想清理或者重装时卡住了。Windows上卸载相对简单项目目录和控制面板里的卸载项处理干净即可但别忘了把系统环境变量里手动加过的ffmpeg路径一并删掉。macOS上用brew装过的依赖可以通过brew uninstall清理用户目录下的配置文件单独删。Linux下如果走了systemd服务要先停服务再删文件。重装场景我遇到的最多的问题是旧配置里残留的Key和端口信息导致新实例启动失败。所以无论哪个平台卸载或重装前第一步都应该是备份配置目录第二步彻底清理环境变量和临时文件第三步再动依赖和代码。我个人的习惯是把OpenClaw的配置目录整个打压缩包存起来重装后直接恢复省去重新配置模型和Skill的功夫。这段时间在三平台反复折腾OpenClaw最大的收获就是彻底搞懂了这类Agent框架的部署逻辑先备环境、再跑代码、然后调模型、最后折腾扩展。每一步的坑其实都大同小异根子还是那些原生依赖、路径、权限、版本的老问题。如果你照着这篇文章部署时仍然遇到我写漏的坑建议先冷静看日志确认好报错关键词再搜方案大部分问题都能用这个笨办法解决。等把OpenClaw真正跑起来、接上你自己调好的模型你会觉得前面所有折腾都值回票价。