做AI智能体这类项目最难的不是模型本身而是怎么把环境折腾顺。openclaw这个框架我盯着有一阵子了它把“技能”和“算力调用”做成了很舒服的插件式结构部署形态又特别灵活——Windows、WSL、Ubuntu都能跑。但恰恰是这种灵活让不少人在安装阶段就被卡住尤其在国内网络环境下WSL拉发行版、Ubuntu装依赖、API基座配置每一步都有暗坑。这篇东西我按自己实际踩过的路子从零开始把openclaw装到Win10(WSL)和Ubuntu24上尽量把选择背后的逻辑也讲清楚你照着做能少折腾两三天。1. 部署前的整体思路为什么是WSL2加Ubuntu24.041.1 我为什么不用纯Windows或虚拟机openclaw本身是个偏服务端形态的框架底层依赖大量Linux生态的工具链。如果在纯Windows上直接跑光是环境变量、动态链接库和各类二进制兼容问题就能劝退大部分人。虚拟机方案又太重每次启动要等系统完整引导资源占用动不动几个G内存开发体验非常割裂。WSL2的好处是它跑在轻量级虚拟机里但文件系统、网络、剪贴板跟Windows是打通的。你可以在Windows的VSCode里直接连着WSL的Ubuntu写代码run指令在WSL侧执行文件却能直接放在Windows目录下。对openclaw这种既要Linux环境、又要跟Windows桌面工具配合的框架来说WSL2几乎是目前最合理的落脚点。Ubuntu24.04我推荐的原因只有一个库够新、社区活跃。openclaw依赖的Python版本、Node运行时还有一些系统级库在24.04上都能直接用apt拉到合适的版本不用像在Debian老版本或者CentOS上那样到处编译。24.04是LTS版支持周期长跑这种长期服务的框架更省心。1.2 部署openclaw前需要先明确的三件事第一你的算力从哪里来。openclaw支持本地跑模型但更推荐的方式是接入API。它本身不绑定任何特定推理后端只要把OpenAI兼容的API地址和密钥填进配置就能把记忆、技能调用这些活交给一个小模型把复杂推理交给云端大模型。这个架构设计非常务实本地只跑轻量的编排逻辑不会把GPU吃满。第二技能的存储方式。openclaw的技能本质是一组可复用的指令模板和工具脚本按目录组织每个技能一个子目录内部有描述文件和调用入口。安装框架本身只是第一步真正让openclaw发挥作用的是往技能目录里塞东西。这个机制决定了它的扩展性也决定了你后续维护时会经常操作文件系统。第三Windows Companion组件。这个组件是为了让WSL里的openclaw能调用Windows侧的工具和服务比如通过Windows的命令行执行一些本地操作。如果你只是做纯文本类的智能体实验这个组件可以后装。但如果想让智能体跟本机应用联动这个必须提前留好位置。2. Win10上安装WSL2的完整流程与避坑2.1 前置系统配置折腾前先检查这四样东西Win10能不能舒服地跑WSL2关键看系统版本和虚拟化相关设置。我建议至少在Windows 10 2004及以上版本操作最好是21H2以后的版本因为WSL的安装命令在较新版本里才支持一键式操作。需要提前确认的几项BIOS里要打开虚拟化技术Intel叫VT-xAMD叫SVM这个不开WSL2起不来。系统设置里“Windows功能”需要启用“适用于Linux的Windows子系统”和“虚拟机平台”两个选项。如果之前装过WSL1需要先用wsl --set-default-version 2把默认版本切到WSL2。检查Windows安全中心里的“内核隔离”是否开启这个有时候会跟WSL2的虚拟化层冲突出现装完启动不了的情况。还有个容易忽略的点C盘空间一定要留够。WSL2的虚拟磁盘文件默认存在C盘虽然下面会讲怎么改路径但建议哪怕是临时用C盘至少留出20G以上空间免得装到一半磁盘爆掉整个虚拟磁盘文件损坏。2.2 三步完成WSL2安装第一步用管理员身份打开PowerShell或Cmd窗口执行wsl --install这条命令在较新的Win10版本里会默认安装WSL2内核并且会拉取Ubuntu发行版。如果你的系统版本偏老命令不支持就手动分两步先启用功能再装执行完两条命令后重启dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart第二步安装指定发行版。如果你不想用默认的Ubuntu或者想直接指定版本wsl --install -d Ubuntu-24.04这里有个国内网络环境下常见的问题下载发行版镜像时非常慢甚至卡在0%。原因是镜像托管在微软的CDN上某些地区连接不稳定。解决方案是设置镜像源在WSL安装前先配置%USERPROFILE%\.wslconfig文件[wsl2] memory8GB swap0 localhostForwardingtruelocalhostForwarding这行很重要它决定了Windows能否通过localhost直接访问WSL里跑的服务。openclaw起服务后如果Windows浏览器访问不了多半就是这里被关了。第三步设置WSL默认版本并启动Ubuntuwsl --set-default-version 2 wsl --set-default Ubuntu-24.04 wsl ~首次进入Ubuntu会提示创建用户名和密码。这个用户名会映射到WSL内的home目录建议用简短的名字避免后续路径太长出幺蛾子。2.3 把WSL迁移到非系统盘的正确姿势C盘空间吃紧是个绕不开的坑。WSL的虚拟磁盘默认存放在C:\Users\用户名\AppData\Local\Packages\下的某个目录里时间一长就膨胀到好几G。openclaw要拉模型、装依赖虚拟磁盘只会越来越大。迁移步骤我实测过最稳的是导出再导入wsl --shutdown wsl --export Ubuntu-24.04 D:\wsl\ubuntu24.tar wsl --unregister Ubuntu-24.04 wsl --import Ubuntu-24.04 D:\wsl\ubuntu24 D:\wsl\ubuntu24.tar --version 2注意几点--unregister会删除当前发行版的所有数据和配置所以导出文件一定要先确认生成成功导入后默认用户会变成root需要进到系统里修改默认用户。操作如下# 进入WSL后执行 echo 用户名 /etc/wsl.conf # 编辑/etc/wsl.conf加入如下内容 [user] default你的用户名改完之后在Windows里执行wsl --shutdown再重启WSL用户就对了。另一个替代方案是在.wslconfig里把虚拟磁盘位置指过去但这属于进阶玩法新手不建议折腾。3. Ubuntu24.04系统内的环境准备3.1 换源、更新、基础组件一个都别省WSL里的Ubuntu默认用的是国外源下载速度在国内网络环境里非常感人。第一步一定是换源让apt能正常干活。我先备份原始源文件然后编辑sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update sudo apt upgrade -y阿里云镜像源是相对稳定的选择。如果你在其它地区用中科大、清华的源也可以逻辑都是一样的——把域名替换成国内可达的镜像地址。更新完成后建议顺手装一批基础工具sudo apt install -y build-essential curl wget git unzip zip python3-pip python3-venv这些基本是openclaw安装脚本的前置依赖提前准备好能少报一堆莫名其妙的错。3.2 Python环境管理和Node运行时openclaw的安装脚本一般会自己处理依赖但我建议你提前把Python环境理干净避免系统Python和虚拟环境打架。推荐直接用python3-venv建独立环境。openclaw如果官方给了安装脚本大概率是基于Python的会装一堆依赖。如果不隔离后面跟系统包冲突时非常痛苦。mkdir -p ~/apps/openclaw cd ~/apps/openclaw python3 -m venv .venv source .venv/bin/activateNode方面如果openclaw的前端界面或某些插件需要Node运行时建议用nvm安装而不是直接apt装。apt里的Node版本通常偏老插件兼容性容易出问题。nvm的安装方式curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完重开终端nvm install 20然后nvm use 20。这个步骤不是必须的但如果你后面想跑带WebUI的插件一定会用上。3.3 中文输入法和基础体验设置很多人在WSL里装完Ubuntu发现不能输中文这个其实要分两层来看。如果你只是在终端里跑openclaw命令终端本身是Windows Terminal的话中文输入法在WSL里直接能用。但如果要装图形界面的中文输入法那要额外配置fcitx或ibus。搜狗输入法在Ubuntu24上装会踩坑因为24.04的GTK版本和Qt依赖跟老版本不完全兼容。如果确实需要中文输入我建议先装fcitx5加fcitx5-chinese-addons比硬磕搜狗省时间。sudo apt install -y fcitx5 fcitx5-chinese-addons fcitx5-config-qt装完设置环境变量把输入法框架切到fcitx5然后重启WSL。这一步跟openclaw没有直接关系但如果你打算用终端交互方式跟智能体对话中文输入的稳定性直接影响体验。4. openclaw的核心安装与配置4.1 官方安装脚本、Docker和源码安装该选哪种openclaw提供了几种部署方式我以自身实测经验把三种方式的适用场景和坑位先摊开讲。官方安装脚本是最省事的一条命令拉完所有依赖自动创建配置目录。适合第一次部署、只想快速跑通框架的场景。脚本安装的位置通常在~/.openclaw/下配置文件和技能目录都集中在这里后续查找方便。Docker方式适合不想污染系统环境、或者需要迁移部署的场景。openclaw的镜像在构建时会把依赖全部打进层里业务代码用挂载卷的方式映射。这种方式的好处是升级方便缺点是网络波动时拉镜像会失败而且和Windows Companion的联动会多一层端口转发配置排查起来比较绕。源码安装最灵活你可以改框架本身的逻辑适合研究型玩家。但代价是要自己解决所有依赖问题Python包之间的版本冲突会把你搞到怀疑人生。我自己的建议是先脚本装一遍跑通再视需求切源码或Docker。4.2 脚本安装的完整执行记录安装前确保虚拟环境激活状态然后执行curl -fsSL https://openclaw.example.com/install.sh | bash注意上面这串地址是我演示用的真实地址以openclaw官方仓库为准。遇到网络超时不要反复重试同一个命令先检查网络再考虑是不是需要走代理镜像。国内网络环境下载经常卡在某个依赖上建议在空闲时段执行或者配置了稳定的网络后再继续。安装脚本跑完后会输出一个配置目录路径和启动命令。我第一次装的时候没有认真看输出导致后面找配置文件找了半天。正常路径一般是~/.openclaw/config.yaml打开这个配置文件你会看到几个关键字段api_base: https://api.openai.com/v1 api_key: sk-xxxx model: gpt-4o-mini skill_dir: ~/.openclaw/skillsapi_base和api_key是接入算力的入口。如果你用的是国内的大模型API把api_base改成对应服务商提供的地址就行只要接口协议是OpenAI兼容格式openclaw一般都能直接认。model字段可以换成实际可用的模型名比如qwen-plus之类的厂商模型标识。我顺便说一下“openclaw只能用接入API的方式使用算力吗”这个问题。当然不是它同样支持本地推理。只要在配置里把api_base指到本地运行的推理服务地址比如http://localhost:11434/v1配合Ollama或者指向http://localhost:8080/v1配合vLLM就能实现本地推理。实测下来本地推理的延迟更低、数据不出本机但对机器配置要求高显存至少要能满足模型加载需求。API方式的好处是弹性大不用操心硬件。两种方式可以根据场景切换甚至同一个框架里配多个模型服务都行。4.3 技能目录与首次启动验证openclaw最核心的扩展机制是Skill。它本质上是一组带描述信息的指令模板框架通过解析技能描述来决定什么时候调用哪个技能。技能目录里每个子文件夹代表一个技能里面通常包含SKILL.md技能描述文件写清楚这个技能干什么、需要什么参数run.py或类似的可执行入口被调用时执行的逻辑可能还有辅助脚本、配置文件安装完成后我先执行一个简单技能来验证框架状态。openclaw通常自带一两个内置技能比如获取系统时间、查询天气之类。我建议先跑这些验证安装链路是否通畅openclaw run 现在几点了如果返回了正常的时间信息说明框架本体、模型API、技能加载三个环节都通了。如果这里卡住优先排查API密钥是不是填错、网络能不能通到api_base、模型名是否正确。4.4 Windows Companion组件的配置逻辑Windows Companion是让WSL里的openclaw能触达Windows系统能力的桥接组件。它在Windows侧跑一个轻量服务WSL里的openclaw通过HTTP或Socket跟它通信从而执行Windows命令、弹系统通知、访问Windows文件系统等。配置方法是先确保WSL里的openclaw已经启动了服务然后在Windows侧运行Companion的安装程序或启动脚本。它默认会监听一个本地端口比如127.0.0.1:8765。这里最关键的坑是防火墙。Windows Defender防火墙会拦截来自WSL虚拟网卡的网络请求表现就是WSL里的openclaw一直报连接超时。解决办法是给Companion程序添加一条入站规则允许它在专用网络上通信。还有一种简单方案如果Companion只服务本机WSL直接在设置里绑定127.0.0.1就行不开放到局域网减少暴露面。5. 常见问题与排查技巧实录5.1 WSL安装和启动阶段的典型故障一直卡在“Installing, this may take a few minutes…”这个基本是网络问题。WSL从微软服务器拉取发行版镜像时某些网络环境下会长时间无响应。处理方法把wsl --install -d Ubuntu-24.04过程中下载中断的残留清掉重新设置.wslconfig里的镜像参数或者手工下载Ubuntu的appx包后安装。报错“请启用适用于 Linux 的 Windows 子系统”功能开关没打开。老版本Windows上这个功能默认是关的需要手动勾选或者用前面提到的dism.exe命令开启然后重启系统。如果已经开启还报错多半是没重启。0x80370102 错误虚拟机平台没有正确启用。排查顺序BIOS虚拟化开关、Windows功能列表里的“虚拟机平台”、Hyper-V是否跟第三方虚拟化软件冲突。5.2 openclaw运行时的经典报错ModuleNotFoundError框架启动时报Python模块缺失。大部分情况是依赖没装全。最简单粗暴的解法是切到虚拟环境重新执行一遍安装脚本它会重新扫描并补齐缺失依赖。如果还不行手动安装报错模块pip install 模块名。端口被占用openclaw默认管理端口如果被其他服务占了启动会直接退出。排查用netstat -ano | findstr 端口号看是谁占的。我遇到过是Docker Desktop启动后把某个端口抢走了关掉Docker再启动openclaw就好了。API请求一直超时网络不通、API地址不对、密钥失效都有可能。逐层排查先curl一下api_base看通不通再确认密钥前缀对不对再看模型名是否匹配服务商那边可用模型列表。5.3 Ubuntu24.04周边环境问题速查问题现象解决思路搜狗输入法装不上依赖冲突、安装后无法激活改用fcitx5加中文字典网络太慢apt、git、pip都慢换国内镜像源pip用清华源VisualBox装Ubuntu黑屏开机卡在黑屏界面显卡控制器改为VBoxSVGA启用3D加速Docker Desktop更新后WSL卡死WSL启动不了Docker图标转圈重启Docker服务必要时wsl --shutdown再启重启后盘符消失Windows下D盘不见了检查磁盘管理确认虚拟磁盘是否有挂载异常不要直接用--unregister5.4 在VSCode中使用WSL的开发姿势openclaw装好后真正高频的操作是改技能目录里的Python脚本和配置文件。直接在WSL的终端里用vim改文件不是不行但体验远不如VSCode。VSCode里装好“WSL”插件后按F1输入“WSL: Connect to WSL”就能进到Ubuntu环境。这时候左侧打开的就是WSL内的文件系统可以直接编辑~/.openclaw/下的所有文件终端也会自动切到WSL的shell。这个组合键我一天要按几十次是openclaw开发调试的核心姿势。调试时我习惯在VSCode里直接运行openclaw run 测试指令配合断点看技能脚本的执行流程比在纯终端里盲改快得多。如果你需要改框架源码用这个方式也最顺手。6. 一些很实在的收尾建议最后分享两个我在实际部署中获得的经验。第一openclaw这类框架的安装文档再好也不如把目录结构吃透来得实在。装完之后花半小时把安装目录下的config.yaml、skills/、logs/三个地方都翻一遍搞清楚谁是谁后面调参和排错都会轻松很多。第二技能文件是文本可以先拿简单模板练手把一个技能的SKILL.md写通、写规范比直接复制十几个别人写的技能更有价值——因为技能描述和实际执行的匹配度只能靠自己一点点调出来。我踩过最重的坑就是第一次启动时没有做最小验证一上来就塞了一大堆技能和复杂的系统提示词结果出了问题完全分不清是框架有问题还是技能脚本报错。后来养成习惯了新装环境第一步永远跑内置技能第二步加一个自己写的最小技能第三步再加API配置调优每一步都验证通过再往下走。这套思路不仅适用于openclaw任何插件式AI框架都通用。现在环境稳定跑了两个多月技能目录里攒了几十个自己写的技能中途系统升级、Docker冲突、WSL路径变动都遇到过了靠着这套“小步验证”的流程每次都能快速恢复到正常状态。 
长河君 · 2026/10/8 15:01:05 · 阅读 1.2k openclaw部署实战：Win10 WSL与Ubuntu24.04全流程避坑指南
做AI智能体这类项目最难的不是模型本身而是怎么把环境折腾顺。openclaw这个框架我盯着有一阵子了它把“技能”和“算力调用”做成了很舒服的插件式结构部署形态又特别灵活——Windows、WSL、Ubuntu都能跑。但恰恰是这种灵活让不少人在安装阶段就被卡住尤其在国内网络环境下WSL拉发行版、Ubuntu装依赖、API基座配置每一步都有暗坑。这篇东西我按自己实际踩过的路子从零开始把openclaw装到Win10(WSL)和Ubuntu24上尽量把选择背后的逻辑也讲清楚你照着做能少折腾两三天。1. 部署前的整体思路为什么是WSL2加Ubuntu24.041.1 我为什么不用纯Windows或虚拟机openclaw本身是个偏服务端形态的框架底层依赖大量Linux生态的工具链。如果在纯Windows上直接跑光是环境变量、动态链接库和各类二进制兼容问题就能劝退大部分人。虚拟机方案又太重每次启动要等系统完整引导资源占用动不动几个G内存开发体验非常割裂。WSL2的好处是它跑在轻量级虚拟机里但文件系统、网络、剪贴板跟Windows是打通的。你可以在Windows的VSCode里直接连着WSL的Ubuntu写代码run指令在WSL侧执行文件却能直接放在Windows目录下。对openclaw这种既要Linux环境、又要跟Windows桌面工具配合的框架来说WSL2几乎是目前最合理的落脚点。Ubuntu24.04我推荐的原因只有一个库够新、社区活跃。openclaw依赖的Python版本、Node运行时还有一些系统级库在24.04上都能直接用apt拉到合适的版本不用像在Debian老版本或者CentOS上那样到处编译。24.04是LTS版支持周期长跑这种长期服务的框架更省心。1.2 部署openclaw前需要先明确的三件事第一你的算力从哪里来。openclaw支持本地跑模型但更推荐的方式是接入API。它本身不绑定任何特定推理后端只要把OpenAI兼容的API地址和密钥填进配置就能把记忆、技能调用这些活交给一个小模型把复杂推理交给云端大模型。这个架构设计非常务实本地只跑轻量的编排逻辑不会把GPU吃满。第二技能的存储方式。openclaw的技能本质是一组可复用的指令模板和工具脚本按目录组织每个技能一个子目录内部有描述文件和调用入口。安装框架本身只是第一步真正让openclaw发挥作用的是往技能目录里塞东西。这个机制决定了它的扩展性也决定了你后续维护时会经常操作文件系统。第三Windows Companion组件。这个组件是为了让WSL里的openclaw能调用Windows侧的工具和服务比如通过Windows的命令行执行一些本地操作。如果你只是做纯文本类的智能体实验这个组件可以后装。但如果想让智能体跟本机应用联动这个必须提前留好位置。2. Win10上安装WSL2的完整流程与避坑2.1 前置系统配置折腾前先检查这四样东西Win10能不能舒服地跑WSL2关键看系统版本和虚拟化相关设置。我建议至少在Windows 10 2004及以上版本操作最好是21H2以后的版本因为WSL的安装命令在较新版本里才支持一键式操作。需要提前确认的几项BIOS里要打开虚拟化技术Intel叫VT-xAMD叫SVM这个不开WSL2起不来。系统设置里“Windows功能”需要启用“适用于Linux的Windows子系统”和“虚拟机平台”两个选项。如果之前装过WSL1需要先用wsl --set-default-version 2把默认版本切到WSL2。检查Windows安全中心里的“内核隔离”是否开启这个有时候会跟WSL2的虚拟化层冲突出现装完启动不了的情况。还有个容易忽略的点C盘空间一定要留够。WSL2的虚拟磁盘文件默认存在C盘虽然下面会讲怎么改路径但建议哪怕是临时用C盘至少留出20G以上空间免得装到一半磁盘爆掉整个虚拟磁盘文件损坏。2.2 三步完成WSL2安装第一步用管理员身份打开PowerShell或Cmd窗口执行wsl --install这条命令在较新的Win10版本里会默认安装WSL2内核并且会拉取Ubuntu发行版。如果你的系统版本偏老命令不支持就手动分两步先启用功能再装执行完两条命令后重启dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart第二步安装指定发行版。如果你不想用默认的Ubuntu或者想直接指定版本wsl --install -d Ubuntu-24.04这里有个国内网络环境下常见的问题下载发行版镜像时非常慢甚至卡在0%。原因是镜像托管在微软的CDN上某些地区连接不稳定。解决方案是设置镜像源在WSL安装前先配置%USERPROFILE%\.wslconfig文件[wsl2] memory8GB swap0 localhostForwardingtruelocalhostForwarding这行很重要它决定了Windows能否通过localhost直接访问WSL里跑的服务。openclaw起服务后如果Windows浏览器访问不了多半就是这里被关了。第三步设置WSL默认版本并启动Ubuntuwsl --set-default-version 2 wsl --set-default Ubuntu-24.04 wsl ~首次进入Ubuntu会提示创建用户名和密码。这个用户名会映射到WSL内的home目录建议用简短的名字避免后续路径太长出幺蛾子。2.3 把WSL迁移到非系统盘的正确姿势C盘空间吃紧是个绕不开的坑。WSL的虚拟磁盘默认存放在C:\Users\用户名\AppData\Local\Packages\下的某个目录里时间一长就膨胀到好几G。openclaw要拉模型、装依赖虚拟磁盘只会越来越大。迁移步骤我实测过最稳的是导出再导入wsl --shutdown wsl --export Ubuntu-24.04 D:\wsl\ubuntu24.tar wsl --unregister Ubuntu-24.04 wsl --import Ubuntu-24.04 D:\wsl\ubuntu24 D:\wsl\ubuntu24.tar --version 2注意几点--unregister会删除当前发行版的所有数据和配置所以导出文件一定要先确认生成成功导入后默认用户会变成root需要进到系统里修改默认用户。操作如下# 进入WSL后执行 echo 用户名 /etc/wsl.conf # 编辑/etc/wsl.conf加入如下内容 [user] default你的用户名改完之后在Windows里执行wsl --shutdown再重启WSL用户就对了。另一个替代方案是在.wslconfig里把虚拟磁盘位置指过去但这属于进阶玩法新手不建议折腾。3. Ubuntu24.04系统内的环境准备3.1 换源、更新、基础组件一个都别省WSL里的Ubuntu默认用的是国外源下载速度在国内网络环境里非常感人。第一步一定是换源让apt能正常干活。我先备份原始源文件然后编辑sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update sudo apt upgrade -y阿里云镜像源是相对稳定的选择。如果你在其它地区用中科大、清华的源也可以逻辑都是一样的——把域名替换成国内可达的镜像地址。更新完成后建议顺手装一批基础工具sudo apt install -y build-essential curl wget git unzip zip python3-pip python3-venv这些基本是openclaw安装脚本的前置依赖提前准备好能少报一堆莫名其妙的错。3.2 Python环境管理和Node运行时openclaw的安装脚本一般会自己处理依赖但我建议你提前把Python环境理干净避免系统Python和虚拟环境打架。推荐直接用python3-venv建独立环境。openclaw如果官方给了安装脚本大概率是基于Python的会装一堆依赖。如果不隔离后面跟系统包冲突时非常痛苦。mkdir -p ~/apps/openclaw cd ~/apps/openclaw python3 -m venv .venv source .venv/bin/activateNode方面如果openclaw的前端界面或某些插件需要Node运行时建议用nvm安装而不是直接apt装。apt里的Node版本通常偏老插件兼容性容易出问题。nvm的安装方式curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完重开终端nvm install 20然后nvm use 20。这个步骤不是必须的但如果你后面想跑带WebUI的插件一定会用上。3.3 中文输入法和基础体验设置很多人在WSL里装完Ubuntu发现不能输中文这个其实要分两层来看。如果你只是在终端里跑openclaw命令终端本身是Windows Terminal的话中文输入法在WSL里直接能用。但如果要装图形界面的中文输入法那要额外配置fcitx或ibus。搜狗输入法在Ubuntu24上装会踩坑因为24.04的GTK版本和Qt依赖跟老版本不完全兼容。如果确实需要中文输入我建议先装fcitx5加fcitx5-chinese-addons比硬磕搜狗省时间。sudo apt install -y fcitx5 fcitx5-chinese-addons fcitx5-config-qt装完设置环境变量把输入法框架切到fcitx5然后重启WSL。这一步跟openclaw没有直接关系但如果你打算用终端交互方式跟智能体对话中文输入的稳定性直接影响体验。4. openclaw的核心安装与配置4.1 官方安装脚本、Docker和源码安装该选哪种openclaw提供了几种部署方式我以自身实测经验把三种方式的适用场景和坑位先摊开讲。官方安装脚本是最省事的一条命令拉完所有依赖自动创建配置目录。适合第一次部署、只想快速跑通框架的场景。脚本安装的位置通常在~/.openclaw/下配置文件和技能目录都集中在这里后续查找方便。Docker方式适合不想污染系统环境、或者需要迁移部署的场景。openclaw的镜像在构建时会把依赖全部打进层里业务代码用挂载卷的方式映射。这种方式的好处是升级方便缺点是网络波动时拉镜像会失败而且和Windows Companion的联动会多一层端口转发配置排查起来比较绕。源码安装最灵活你可以改框架本身的逻辑适合研究型玩家。但代价是要自己解决所有依赖问题Python包之间的版本冲突会把你搞到怀疑人生。我自己的建议是先脚本装一遍跑通再视需求切源码或Docker。4.2 脚本安装的完整执行记录安装前确保虚拟环境激活状态然后执行curl -fsSL https://openclaw.example.com/install.sh | bash注意上面这串地址是我演示用的真实地址以openclaw官方仓库为准。遇到网络超时不要反复重试同一个命令先检查网络再考虑是不是需要走代理镜像。国内网络环境下载经常卡在某个依赖上建议在空闲时段执行或者配置了稳定的网络后再继续。安装脚本跑完后会输出一个配置目录路径和启动命令。我第一次装的时候没有认真看输出导致后面找配置文件找了半天。正常路径一般是~/.openclaw/config.yaml打开这个配置文件你会看到几个关键字段api_base: https://api.openai.com/v1 api_key: sk-xxxx model: gpt-4o-mini skill_dir: ~/.openclaw/skillsapi_base和api_key是接入算力的入口。如果你用的是国内的大模型API把api_base改成对应服务商提供的地址就行只要接口协议是OpenAI兼容格式openclaw一般都能直接认。model字段可以换成实际可用的模型名比如qwen-plus之类的厂商模型标识。我顺便说一下“openclaw只能用接入API的方式使用算力吗”这个问题。当然不是它同样支持本地推理。只要在配置里把api_base指到本地运行的推理服务地址比如http://localhost:11434/v1配合Ollama或者指向http://localhost:8080/v1配合vLLM就能实现本地推理。实测下来本地推理的延迟更低、数据不出本机但对机器配置要求高显存至少要能满足模型加载需求。API方式的好处是弹性大不用操心硬件。两种方式可以根据场景切换甚至同一个框架里配多个模型服务都行。4.3 技能目录与首次启动验证openclaw最核心的扩展机制是Skill。它本质上是一组带描述信息的指令模板框架通过解析技能描述来决定什么时候调用哪个技能。技能目录里每个子文件夹代表一个技能里面通常包含SKILL.md技能描述文件写清楚这个技能干什么、需要什么参数run.py或类似的可执行入口被调用时执行的逻辑可能还有辅助脚本、配置文件安装完成后我先执行一个简单技能来验证框架状态。openclaw通常自带一两个内置技能比如获取系统时间、查询天气之类。我建议先跑这些验证安装链路是否通畅openclaw run 现在几点了如果返回了正常的时间信息说明框架本体、模型API、技能加载三个环节都通了。如果这里卡住优先排查API密钥是不是填错、网络能不能通到api_base、模型名是否正确。4.4 Windows Companion组件的配置逻辑Windows Companion是让WSL里的openclaw能触达Windows系统能力的桥接组件。它在Windows侧跑一个轻量服务WSL里的openclaw通过HTTP或Socket跟它通信从而执行Windows命令、弹系统通知、访问Windows文件系统等。配置方法是先确保WSL里的openclaw已经启动了服务然后在Windows侧运行Companion的安装程序或启动脚本。它默认会监听一个本地端口比如127.0.0.1:8765。这里最关键的坑是防火墙。Windows Defender防火墙会拦截来自WSL虚拟网卡的网络请求表现就是WSL里的openclaw一直报连接超时。解决办法是给Companion程序添加一条入站规则允许它在专用网络上通信。还有一种简单方案如果Companion只服务本机WSL直接在设置里绑定127.0.0.1就行不开放到局域网减少暴露面。5. 常见问题与排查技巧实录5.1 WSL安装和启动阶段的典型故障一直卡在“Installing, this may take a few minutes…”这个基本是网络问题。WSL从微软服务器拉取发行版镜像时某些网络环境下会长时间无响应。处理方法把wsl --install -d Ubuntu-24.04过程中下载中断的残留清掉重新设置.wslconfig里的镜像参数或者手工下载Ubuntu的appx包后安装。报错“请启用适用于 Linux 的 Windows 子系统”功能开关没打开。老版本Windows上这个功能默认是关的需要手动勾选或者用前面提到的dism.exe命令开启然后重启系统。如果已经开启还报错多半是没重启。0x80370102 错误虚拟机平台没有正确启用。排查顺序BIOS虚拟化开关、Windows功能列表里的“虚拟机平台”、Hyper-V是否跟第三方虚拟化软件冲突。5.2 openclaw运行时的经典报错ModuleNotFoundError框架启动时报Python模块缺失。大部分情况是依赖没装全。最简单粗暴的解法是切到虚拟环境重新执行一遍安装脚本它会重新扫描并补齐缺失依赖。如果还不行手动安装报错模块pip install 模块名。端口被占用openclaw默认管理端口如果被其他服务占了启动会直接退出。排查用netstat -ano | findstr 端口号看是谁占的。我遇到过是Docker Desktop启动后把某个端口抢走了关掉Docker再启动openclaw就好了。API请求一直超时网络不通、API地址不对、密钥失效都有可能。逐层排查先curl一下api_base看通不通再确认密钥前缀对不对再看模型名是否匹配服务商那边可用模型列表。5.3 Ubuntu24.04周边环境问题速查问题现象解决思路搜狗输入法装不上依赖冲突、安装后无法激活改用fcitx5加中文字典网络太慢apt、git、pip都慢换国内镜像源pip用清华源VisualBox装Ubuntu黑屏开机卡在黑屏界面显卡控制器改为VBoxSVGA启用3D加速Docker Desktop更新后WSL卡死WSL启动不了Docker图标转圈重启Docker服务必要时wsl --shutdown再启重启后盘符消失Windows下D盘不见了检查磁盘管理确认虚拟磁盘是否有挂载异常不要直接用--unregister5.4 在VSCode中使用WSL的开发姿势openclaw装好后真正高频的操作是改技能目录里的Python脚本和配置文件。直接在WSL的终端里用vim改文件不是不行但体验远不如VSCode。VSCode里装好“WSL”插件后按F1输入“WSL: Connect to WSL”就能进到Ubuntu环境。这时候左侧打开的就是WSL内的文件系统可以直接编辑~/.openclaw/下的所有文件终端也会自动切到WSL的shell。这个组合键我一天要按几十次是openclaw开发调试的核心姿势。调试时我习惯在VSCode里直接运行openclaw run 测试指令配合断点看技能脚本的执行流程比在纯终端里盲改快得多。如果你需要改框架源码用这个方式也最顺手。6. 一些很实在的收尾建议最后分享两个我在实际部署中获得的经验。第一openclaw这类框架的安装文档再好也不如把目录结构吃透来得实在。装完之后花半小时把安装目录下的config.yaml、skills/、logs/三个地方都翻一遍搞清楚谁是谁后面调参和排错都会轻松很多。第二技能文件是文本可以先拿简单模板练手把一个技能的SKILL.md写通、写规范比直接复制十几个别人写的技能更有价值——因为技能描述和实际执行的匹配度只能靠自己一点点调出来。我踩过最重的坑就是第一次启动时没有做最小验证一上来就塞了一大堆技能和复杂的系统提示词结果出了问题完全分不清是框架有问题还是技能脚本报错。后来养成习惯了新装环境第一步永远跑内置技能第二步加一个自己写的最小技能第三步再加API配置调优每一步都验证通过再往下走。这套思路不仅适用于openclaw任何插件式AI框架都通用。现在环境稳定跑了两个多月技能目录里攒了几十个自己写的技能中途系统升级、Docker冲突、WSL路径变动都遇到过了靠着这套“小步验证”的流程每次都能快速恢复到正常状态。