1. 一键脚本装OpenClaw总失败先把安装过程拆开看OpenClaw这个开源AI智能体项目最近在自动化办公、电商店铺操作、浏览器任务这些场景里热度一直很高不少人都是冲着“装个一键脚本就能跑”来的。结果呢命令行里敲完安装命令屏幕上刷了一堆看不懂的报错卡在同一个地方半小时是常有的事。这篇就把一键脚本安装OpenClaw的思路、常见坑、分平台排查清单和一些真实案例整理出来不管你是想在Windows、Ubuntu、Docker容器还是手机Termux上跑都能照着一节一节查。先说一个基本事实所谓“一键脚本”并不是魔杖它只是在帮你执行一系列固定步骤。脚本默认你的系统里已经有了某些环境和权限但每个人机器环境差距太大——Python版本不同、系统依赖缺失、端口被占用、配置文件没生成脚本又不可能替你做体检于是哪一个环节断了就直接红字报错。所以排查的第一步不是反复重跑脚本而是把脚本做的事拆开看它到底卡在哪一个环节。1.1 打开脚本看清它替你执行了哪五步无论你用的是官方Install脚本还是社区整理的一键脚本OpenClaw的安装流程基本都围绕五件事拿代码、建环境、装依赖、写配置、起服务。拿代码脚本最常见的第一步是把项目仓库clone到当前目录有些版本还会自动切换到一个指定分支。这一阶段失败多表现为网络超时、报Could not resolve host或者目标目录已经存在导致clone中止。建环境用python -m venv .venv或者conda创建一个隔离的Python环境。这一步失败的信号通常是python: command not found或virtualenv相关报错说明系统里根本没有符合要求的Python。装依赖通过pip install -r requirements.txt拉取Python包有些版本还会调用npm安装前端资源。这是全流程最容易翻车的环节失败信息五花八门常见的是编译错误和下载超时。写配置把.env.example复制成.env并填入默认端口、模型服务地址等。脚本只负责“生成”文件不会替你填API Key如果这一步之后你直接启动后面多半会出现401或403。起服务最后启动本地进程或者Docker容器。启动失败的典型报错是Address already in use、Failed to start或者你明明看到服务显示running但浏览器里怎么也打不开管理页。把这五步对应到你看到的报错上问题就已经解决一半。看到pip相关错误就直奔第三步看到端口冲突就直奔第五步而不是从头再来一遍。1.2 装之前先把环境清单过一遍我这几年帮不少朋友排查OpenClaw安装十个里面有七个问题出在环境版本上。建议在跑脚本之前先用下面这张表自查两分钟就能做完检查项最低要求验证命令Python3.10及以上python --versionGit2.x即可git --versionNode/npm只有部分前端页面需要node -v npm -vDocker用容器方式安装才需要docker info磁盘空间建议预留10GB以上df -h验证时有个很容易踩的坑有时你电脑里装了多个Python终端里执行python指向的是3.8但python3可能指向3.10。最靠谱的办法是把python --version和python3 --version都看一眼搞清楚真正会被脚本调用的是哪一个。Windows用户要特别注意如果敲python弹出的是Microsoft Store商店页说明你根本没装好Python只装了一个商店的“应用别名”这是Windows上最隐蔽的安装假象。另外别忽略资源限制。OpenClaw启动后要同时跑服务进程和任务执行进程如果你是用云服务器部署内存低于4GB会非常勉强页面反复加载不出来不一定是你装错了而是进程被系统杀掉。装之前用free -h瞄一眼剩余内存能省掉后面一大串怀疑人生的时间。2. 新手最容易踩的五个坑从报错反推原因这一节我把安装OpenClaw时出现频率最高的五类报错整理了出来每一条都给了定位方法和处理动作。你不需要全看直接按症状找对应编号即可。2.1 依赖下载卡住pip超时、npm一直转圈症状是pip install执行到某个包时反复报Timeout、Retries exceeded或者进度条几分钟不动。OpenClaw的依赖清单里包含了不少体积较大的包默认PyPI源跨地域下载速度并不稳定。解决办法很简单把pip源换到国内镜像。执行命令时可以临时指定pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple如果想一劳永逸可以写进全局配置~/.pip/pip.conf以后安装任何包都会走这个源。如果是npm那一步卡住同样把registry切到国内镜像npm config set registry https://registry.npmmirror.com这里有个实际操作心得很多一键脚本不支持你传-i参数与其反复重跑整个脚本不如自己手动拆分执行。你会发现脚本里其实就是几条命令把pip install那一条抄出来单独加参数执行成功了再回去继续跑后面的步骤。这比在脚本里乱改了再重试要安全得多。2.2 Python版本太老编译报错和ModuleNotFoundError如果你看到Python.h: No such file or directory、ERROR: Failed to build wheel或者ModuleNotFoundError指向了一个明明应该在依赖清单里的包大概率是Python版本不对或者缺少开发头文件。OpenClaw的一键脚本通常默认你有Python 3.10很多服务器自带的是3.8部分依赖包在新版本上才有预编译产物老版本只能现场编译一编译就炸。我的建议是不要动系统自带的Python而是用conda单独创建一个环境conda create -n openclaw python3.10 conda activate openclaw如果不想装condaUbuntu用户可以先安装编译工具链再重试很多编译报错其实只是缺了build-essentialsudo apt update sudo apt install -y build-essential libssl-dev libffi-devWindows用户则去Python官网安装3.10以上版本安装时务必勾选“Add Python to PATH”。装完记得重新打开一个终端再验证版本旧终端里的PATH不会自动刷新你看到的还是旧Python。2.3 Permission denied权限问题比你想象的更常见症状比较直白Permission denied、EACCES、cannot create directory。常见场景有两种一是脚本里用了pip install且你的Python安装在系统目录普通用户没有写权限二是项目clone到了一个root创建的目录里你又用普通用户去执行安装脚本。处理原则是安装阶段能用普通用户就不用root能装到用户目录就装到用户目录。具体动作把项目放在~/openclaw这类用户目录下而不是/opt或/root下面。用虚拟环境跑安装虚拟环境创立在你自己的用户目录里不需要sudo。如果云服务器上是用root登录的建议创建一个普通用户再操作避免后续服务以root运行时出现各种预期外问题。sudo pip install这种写法虽然能绕过权限检查但会把包装进系统Python里污染系统环境。等哪天系统Python升级一堆包全部失效你根本不知道是哪一步埋下的雷。真的没必要。2.4 端口被占用服务起不来或页面打开了但空白症状是启动时报Address already in use或者服务显示运行中但你访问管理页时一直转圈。OpenClaw的Web管理服务会监听一个默认端口你本机如果有其他程序占用了这个端口服务会直接退出但日志往往只有一行不仔细看就错过了。定位占用来源用这几条命令# Linux / macOS ss -tlnp | grep 端口号 # Windows PowerShell netstat -ano | findstr 端口号找到占用进程后要么停掉它要么改OpenClaw的端口。改端口通常就在.env文件里找一个类似PORT或OPENCLAW_PORT的配置项改成你没被占用的数值重启服务即可。排查时我习惯分两步先在本机用curl http://127.0.0.1:端口号试试如果能通说明服务本身没问题你再检查是不是防火墙或安全组拦住了外部访问。这个顺序能帮你快速区分“服务挂了”和“网络不通”。2.5 API Key和环境变量没配对装好了却用不了这是一个“装在逻辑上成功、但实际无法完成任务”的坑。症状是管理界面能打开但一发起任务就报401、403、Authentication failed或者model not found。OpenClaw本身只是一个执行智能体任务的框架思考能力来自你接入的大模型服务所以必须把模型的API Key填到配置里。脚本只会帮你生成.env文件不会替你填内容。你要做的是找到项目根目录下的.env.example文件复制一份命名为.env。按官方文档把模型服务的Key填到对应变量里变量名一般是MODEL_API_KEY或OPENCLAW_API_KEY这类。检查Key前后有没有多余的空格或引号很多人从网页复制Key时会把换行符也复制进去。确认填的是模型服务的API端点base_url不是模型官网主页。这一步如果你之前用过一些本地模型工具很容易把“网页地址”和“API地址”弄混。API地址通常以/v1结尾而登录页地址不是。填错之后服务能正常起来但所有任务都会在执行前认证失败表现非常像“安装错误”实际上只是配置问题。到这里五个常见坑就过完了。下面按平台再过一遍因为同一张报错在不同系统上处理路径差别还挺大的。3. 分平台排查Windows、Ubuntu、Docker和Termux各看这篇3.1 Windows优先用WSL2原生PowerShell会多踩不少坑Windows上装OpenClaw有三条路原生PowerShell、WSL2、Docker Desktop。如果让我排序WSL2优先其次是Docker Desktop最后才是原生PowerShell。原因很简单OpenClaw的安装脚本和文档绝大多数是按Linux习惯写的原生PowerShell里光是路径分隔符、Python商店别名、UTF-8编码乱码就够喝一壶。用WSL2的大致流程是先在“启用或关闭Windows功能”里勾选“适用于Linux的Windows子系统”装好Ubuntu发行版然后在Ubuntu终端里直接执行官方一键脚本。这样遇到问题所有排查方法都和Linux服务器一样网上能找到的参考经验也最多。如果你坚持原生PowerShell有几个点必须检查不要用商店版Python别名装官方Python并勾选PATH执行脚本时如果报执行策略错误需要在管理员终端运行Set-ExecutionPolicy RemoteSigned看到中文乱码可以把终端编码切到UTF-8否则你连报错信息都读不完整。另外热搜里常有人问“OpenClaw Windows Companion怎么配置”。这个组件在新版里负责接入Windows桌面和浏览器操作它的常见问题是开机没有自动启动。排查时先打开任务管理器看有没有Companion进程没有就去安装目录手动启动一次再回去看主程序日志基本就能定位。3.2 Ubuntu/云服务器先把系统依赖补齐再用systemd管服务Linux上一键脚本的通过率其实最高但栽跟头也最集中。第一刀通常砍在缺少编译依赖尤其是一个干净的全新云服务器连build-essential都没有安装依赖时几乎必报编译错误。跑脚本之前先执行sudo apt update sudo apt install -y build-essential git curl如果涉及前端资源打包还需要Node环境可以用nvm装一套避免系统源里的Node版本太旧。服务启动方式建议直接用systemd。很多人图省事用nohup python main.py 等SSH断开或内存波动后服务没了还以为是安装有问题。写一个简单的unit文件放到/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] User你的用户名 WorkingDirectory/home/你的用户名/openclaw ExecStart/home/你的用户名/openclaw/.venv/bin/python main.py Restarton-failure [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw。这样哪怕进程意外退出systemd也会帮你拉起来。排查时用journalctl -u openclaw -f看实时日志比盯着命令行终端方便得多。3.3 Docker方式镜像拉取、挂载目录和环境变量三件事如果你不想在物理机里折腾依赖用Docker装OpenClaw通常会省时间。一个典型的启动命令长这样端口和镜像名以官方最新文档为准docker run -d \ --name openclaw \ -p 127.0.0.1:8787:8787 \ -v ~/openclaw-data:/data \ -e OPENCLAW_API_KEY你的Key \ openclaw/openclaw:latestDocker安装的坑主要在三个地方。第一镜像拉取慢或拉不动给Docker daemon配置registry-mirrors用你所在网络环境下可用的镜像地址即可。第二挂载目录权限不一致容器内UID和宿主机UID不一样时容器写/data会报Permission denied处理方法是在宿主机上执行chown把目录归属调整好。第三容器日志里看服务正常但本机访问不了多半是你把端口只映射到了127.0.0.1上或者云服务器安全组没放行。Docker方式还有一个隐藏优点卸载最干净。不要的服务连同容器一起删掉docker rm -f openclaw docker rmi openclaw/openclaw:latest就能清掉大部分残留比本地安装好收拾得多。3.4 Termux手机端能装但要降低预期热搜里“如何用Termux安装OpenClaw手机版”被搜了很多次。Termux是Android上的终端模拟器确实可以装Python和Git也能跑一些轻量脚本但OpenClaw这种要执行浏览器自动化、桌面操作的Agent在Termux里属于“能跑但很勉强”的状态。实操上我不建议在Termux原生环境里直接跑一键脚本因为缺少的依赖太多编译容易失败。更稳的路线是先装proot-distro在里面开一个Ubuntu环境再按Linux方式安装pkg update pkg install -y proot-distro proot-distro install ubuntu proot-distro login ubuntu进入Ubuntu后按3.2节的步骤安装依赖和脚本。手机性能有限内存小跑大型模型任务大概率会卡死或被杀进程所以Termux更合适的定位是远程查看服务状态、临时执行简单指令、做开发调试。如果你想用它正儿八经跑自动化任务还是弄台电脑或服务器更靠谱。4. 真实报错案例排查实录三个典型问题从报错到跑通排查经验这种东西光讲步骤不如记录一次完整过程。下面三个案例是实际操作中经常遇到的按“报错原文—定位思路—解决动作”的顺序写清楚。4.1 pip安装报GCC编译错误卡在同一个包上报错核心行ERROR: Failed building wheel for pydantic-core error: command gcc failed with exit code 1这种报错经常让人以为是包本身有问题换个版本也没用。实际上它传达的信息是你这台机器上没有可用的C编译工具链或者Python版本太老导致源码包需要现场编译而现场编译又缺工具。处理动作先确认系统装了编译工具Ubuntu上执行sudo apt install -y build-essential。用python --version确认版本是3.10以上。删掉之前装到一半的残留虚拟环境可以直接重建。重新执行pip安装如果想更快把PyPI镜像源加上。我实测下来把build-essential装好之后这类编译报错大多会自动消失。很多包在PyPI上有现成的预编译轮子只有环境不满足时才会退回源码编译。轮子装不上才需要编译编译才需要GCC——所以装编译工具是釜底抽薪的做法。4.2 服务显示运行中但浏览器始终打不开管理页面这个案例比较诡异终端里日志打印了一堆启动信息看起来一切正常但浏览器访问就是白屏、超时。定位分成三步走在本机先试curl http://127.0.0.1:端口/如果返回了页面内容或JSON说明服务活着。如果curl通但外部访问不了检查防火墙。Ubuntu上可能是ufw没放行端口sudo ufw allow 端口。如果用的是云服务器还要检查安全组是否放行该端口。很多云厂商默认只开22和80你程序监听在8787但安全组没放行页面自然打不开。还有一种情况容易被忽略服务默认只绑定127.0.0.1也就是只能本机访问。你想用局域网其他机器连需要在配置里把监听地址改成0.0.0.0。这个选项一般写在启动命令或.env里例如HOST0.0.0.0。改地址、放行防火墙、开安全组这三件事做完页面基本就通了。4.3 任务一执行就报401API Key明明填了现象是OpenClaw管理界面正常发起一个自动化任务后日志里迅速出现401 Unauthorized或invalid_api_key。我当时的排查步骤在.env里确认Key是填到正确变量名下不是填错位置。检查Key尾部是否藏了一个不可见换行符。复制时从网页框选往往会带上换行导致认证失败。用命令行直接测一下模型API是否可用排除OpenClaw本身的问题curl -X POST https://你的模型服务地址/v1/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:模型名,messages:[{role:user,content:hi}]}如果curl能正常返回再去看OpenClaw配置文件里的base_url是否写对。经常有人把模型服务的主页地址当成API地址少加了/v1路径或者把http写成了https。这种问题一旦定位是配置问题改完重启服务就好不需要重装也不用反复折腾环境。5. 自救与重装卸载OpenClaw没那么简单弄干净再换版本5.1 一键卸载要清理哪些东西很多人以为卸载就是把项目文件夹删掉其实OpenClaw安装后数据分布在好几个地方。如果只是删文件夹再重新clone老配置和新代码混在一起问题只会越改越乱。要清理的位置大致有项目目录本身包括clone下来的代码和虚拟环境通常直接删除即可。配置与数据目录常见位置是~/.config/openclaw、~/.cache/openclaw里面可能存了登录态、任务记录和模型缓存不清理的话重装后会出现各种奇怪的“历史包袱”。systemd服务如果配置过开机启动先执行sudo systemctl disable --now openclaw再把.service文件删掉。Docker相关容器、镜像、命名卷一起处理命令是docker rm -f openclaw、docker rmi 镜像名如果有命名卷还要执行docker volume rm。清理之前先把想留的东西备份出来。我见过有人删完整个目录才想起来API Key没记录结果还得重新买额度。往下看怎么备份。5.2 重装之前先备份这些设置有些数据删掉就再也找不回来重装前把下面四样备份出来就够了.env文件所有API Key、端口配置都在里面重装后直接复制回去能省很多事。skills/目录你在官方skill之外自定义的技能这个目录往往是花了很多时间调出来的。data/或data.db任务历史、消息记录删了就是真的没了。版本记录重装前看一眼当前版本方便后面回滚。备份命令也很简单把上面几项打包成一个文件tar -czf openclaw-backup.tar.gz .env skills data压在备份里的Key同样要保管好不要传到公共网盘。tar.gz文件本来就是明文丢了等于把API Key也丢了。我一般会把备份包再用加密工具压一层或者放到只有自己能访问的加密盘里。这个细节看着多余等真出事了就知道能救急。5.3 为什么我建议你锁定版本而不是一直用latest用Docker方式安装的人特别喜欢写openclaw/openclaw:latest因为刚开始确实省心。但这个标签在你需要稳定运行时反而是隐患某天重装拉镜像拉到的已经是更新的大版本配置字段变了、启动参数变了服务直接起不来。保守做法是用git tag或release页的版本号指定安装版本clone下来后切到某个tag。Docker镜像固定到具体tag不要用latest。如果想记录当前版本进入项目目录执行git rev-parse HEADDocker环境用docker image inspect openclaw:latest | grep id记录镜像ID。重新安装前把旧版本的.env和新版本的示例配置对一遍确认新增了哪些变量。很多人重装后出问题不是安装过程错而是新旧配置对不上。6. 装好之后还要跨过三道门模型接入、skill权限、场景化部署6.1 只用API还是接本地模型先把算力问题想清楚有个热词问“OpenClaw只能用接入API的方式使用算力吗”这个问题很典型。OpenClaw本身不做模型推理它的工作是编排任务、调用工具、操作界面真正写答案、做决策的是你接入的大模型服务。所以你有两种路线。一是接云端API配置最省事按量付费适合任务量不大、追求快速上手的场景。二是接本地模型比如用Ollama部署一个模型然后把OpenClaw的base_url指向http://localhost:11434模型名写Ollama里实际的名字。本地模式的好处是数据不出机器、没有按次计费坏处是要求机器配置够高一个大点的模型至少要16GB内存才跑得顺。选择策略不复杂只是体验和轻量任务API优先做数据敏感或长期离线任务本地优先。如果本地内存紧张还可以考虑尺寸更小的量化和蒸馏模型效果降一点但能跑起来。6.2 skill权限别急着全开先学会最小授权OpenClaw的skill机制可以理解成给Agent配了一套“操作手册”。你允许它调用哪些技能它才去做哪些事不给授权它就只能看不能动。这个设计很务实因为Agent自由度太高反而危险。安装完成后的第一件事建议是把示例skill全部过一遍只保留你用得到的把涉及文件删除、系统配置、大金额操作的skill默认关掉。其次检查默认权限配置里有没有“允许操作所有窗口”之类的开关如果只是常规的网页自动化没必要全开。我见过不少安装阶段好端端的部署上线第一天就出问题原因就是把skill权限拉满Agent在真实环境里做出了不该做的操作。安全这关装好之后就得立规矩。6.3 ROS2等场景的部署别把环境变量漏掉热搜词里有“rosclaw”和“ros2 humble gazebo”的组合说明一部分人装OpenClaw不是为了办公自动化而是想看它和机器人仿真环境结合。这个方向分享一个容易踩的坑如果项目依赖ROS2启动OpenClaw前必须把ROS2的环境变量加载好典型的是先执行source /opt/ros/humble/setup.bash再启动服务。很多人跳过这一步装好了却一直收不到话题消息困惑半天。排查这类问题时先单独跑一下ros2 topic list确认ROS2本身的通信正常再去看OpenClaw日志。如果ROS2正常而OpenClaw收不到数据多半是ROS_DOMAIN_ID不一致——两个进程不在同一个DDS域里自然谁也看不见谁。这类问题跟安装脚本本身无关但它确实会伪装成“安装失败”拿出来提醒一下大家。最后再多说一句我自己的使用体会。装OpenClaw这事最忌“无脑重跑脚本”。每次失败都会留下半截环境重跑只是让新错误盖住旧错误。正确做法永远是看清第一条报错是什么定位它在五步流程里的位置把那个环节修好再往下走。把环境拆开、把配置看清、把权限管住这套安装过程走下来你收获的不只是一个能跑的OpenClaw还有一套排查开源项目的老经验。后面再装别的工具你会顺手很多。