直接开篇。OpenClaw这几天在社区里讨论度很高不少朋友都开始折腾部署。我本来在Windows下用WSL2试了一圈发现坑不少索性直接拿一台Ubuntu机器重装系统干净部署。从系统安装到OpenClaw跑起来前前后后折腾了一周多踩了环境变量配错、GCC编译失败、ollama关联不上、日志刷屏却不报错等一堆问题。这篇就把完整的Ubuntu版安装过程、踩坑记录和最终稳定运行的配置方案一次性写清楚给打算自己动手部署的朋友省点时间。这篇文章适合谁看想在Linux环境下部署OpenClaw、但不想被官方文档里那句“See docs”劝退的人已经在Windows下卡在WSL2或“companion连接不上”的朋友也可以参考这里的纯Linux部署思路还有单纯想搞明白配置文件、skill机制、本地模型怎么关联的人。我会把关键原理也顺带讲明白不只是丢命令给你抄。1. 安装前的基础环境准备1.1 为什么我建议直接用Ubuntu裸机部署OpenClaw本身是一个代理框架安装形态大致分三种Windows下通过companion工具跑、Docker容器方式跑、源码方式直接跑。我一开始在Windows下折腾发现几个很现实的问题WSL2的环境检测偶尔抽风提示“需要在PowerShell中运行wsl --status”之类的检查项文件权限在跨文件系统时偶尔出现诡异问题另外Windows下的守护进程和Linux下的systemd行为不太一样重启策略要自己搭。如果你只是尝鲜Windows companion可以用。但如果你想让OpenClaw长期稳定跑、后面还打算接本地模型做自动化任务我强烈建议直接用Ubuntu。主要原因有三个systemd原生管理服务崩溃后能自动拉起不用自己写定时任务。文件权限模型清晰skill目录、配置目录、日志目录的读写权限不容易混乱。内存和CPU调度更直接跑本地模型比如通过ollama加载qwen2.5-3b时性能损耗比WSL2小不少。我用的是Ubuntu 24.04 LTS内核6.8整体兼容性不错。如果你手里还有22.04 LTS问题也不大OpenClaw依赖的Python 3.10、Node.js 18都能正常装。1.2 系统安装和镜像选择的一点点经验Ubuntu官方镜像下载页面直接拉24.04 LTS桌面版就行别用第三方改版镜像别问为什么问就是干净。U盘写盘工具用Ventoy最省心一个U盘可以同时塞Ubuntu、Windows PE、甚至其它工具的镜像启动菜单选择方便不用反复格式化。安装过程中有几个小细节影响后续使用分区方案建议给/至少留50GB因为后面要装模型文件、日志、Python虚拟环境空间很快会吃紧。如果机器内存小于16GB建议在安装时顺手开swap分区大小设为内存的1倍左右。跑OpenClaw 本地模型时内存压力不小swap是保命用的。一定要勾选“安装第三方软件”和“从网络下载更新”的选项否则显卡驱动、解码器这些基础组件后面要手动补麻烦。装完系统第一件事更新软件源并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y git curl wget build-essential python3 python3-pip python3-venv nodejs npm这个build-essential包很关键它包含gcc、g、make等编译工具。我后面踩过一个GCC安装失败的坑就是因为在纯净系统上直接跳过了这一步就跑去装OpenClaw结果编译原生模块时找不到编译器。1.3 显卡驱动、中文输入法和日常基础问题如果你后面打算让OpenClaw调用本地视觉模型或跑较大规模的推理任务NVIDIA显卡驱动的安装优先级要提前。检查驱动的命令nvidia-smi如果提示找不到命令说明驱动还没装。在Ubuntu 24.04上装官方NVIDIA驱动最稳妥的方式是通过软件源sudo ubuntu-drivers autoinstall装完重启再查nvidia-smi就能看到驱动版本和显存信息。这里有一个之前查过很多次的坑如果你在安装驱动过程中出现循环登录或者图形界面进不去的情况多半是驱动和内核模块版本不匹配在启动时进入恢复模式卸载驱动后重新安装一遍基本能解决。另外USB设备如果经常报usbfs缓冲大小不足可以在/etc/default/grub里加usbcore.usbfs_memory_mb1000这个参数然后update-grub重启。中文输入法这种属于“不影响部署但影响心情”的问题Ubuntu 24.04下装fcitx5 中文输入法引擎就好这里不展开。我的建议是先把系统基础环境清干净再来碰OpenClaw不要一边装框架一边处理输入法、微信这类周边问题排查起来会分心。2. OpenClaw核心安装流程拆解2.1 安装方式选型为什么我选了源码方式OpenClaw的安装方式总体分四种自动脚本、Docker、npm包、源码仓库。我的建议是这样的自动脚本适合第一次试用一条命令跑完但中间步骤黑盒出了问题难定位。Docker环境隔离确实好但如果你要加自定义skill、频繁改配置、或者关联本地模型容器和宿主机的文件映射、网络模式会多出不少麻烦。npm包方式适合程序化集成但配置文件的管理路径不够直观对新手来说不容易找到东西在哪。源码方式我最推荐原因很简单——OpenClaw的配置项、skill目录、日志都在源码目录下明确可见改坏了大不了git reset恢复成本极低。我最终的目录结构是这样规划的~/openclaw/ ├── config/ # 主配置目录 ├── skills/ # skill扩展目录 ├── logs/ # 运行日志 ├── data/ # 模型数据、会话状态 └── src/ # 核心代码后面部署都会围绕这个目录来。2.2 源码获取与依赖安装的完整流程先拉代码cd ~ git clone https://github.com/你的用户名/openclaw.git cd openclaw我这里说明一下OpenClaw当前的仓库结构里核心代码和配置是分离的配置文件用YAML格式组织skill机制有点类似插件系统每个skill是一个独立文件夹里面有指令文件和触发逻辑。这是它区别于普通脚本工具的核心点。接着配置Python虚拟环境python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt这里要注意OpenClaw较新版本对Node.js也有依赖用于处理部分前端组件和自动化交互能力。建议装Node.js LTS版本不要装最新版。我用的版本是20.x对OpenClaw的兼容性比较稳。如果过程中遇到node-gyp相关的编译报错说明缺少Python头文件或编译工具链重新安装build-essential和python3-dev就能解决。2.3 首次初始化与配置文件的核心参数解读依赖装完后先别急着启动看一眼配置文件。OpenClaw默认会在config目录下生成一个config.yaml里面几个关键字段在网络搜索中反复出现我逐个说明agent: name: openclaw mode: interactive # 运行模式interactive / daemon / skill language: zh-CN # 交互语言 model: provider: ollama # 可选openai / ollama / anthropic name: qwen2.5-3b # 模型名称 base_url: http://127.0.0.1:11434 # ollama本地地址 skill: dir: ./skills # skill目录相对路径基于项目根目录 auto_load: true # 是否自动加载全部skillmode字段值得多说一句。interactive模式是命令行问答式适合调试daemon模式是后台常驻配合systemd管理适合长时间跑自动化任务skill模式是按指定技能执行一次就退出适合定时任务场景。model.provider是最近很多人在问的点。OpenClaw本身不是一个模型它是一个代理框架也就是负责理解任务、调用工具、调度流程。算力可以来自云端API也可以来自本地ollama。社区里很多人选择ollama qwen2.5-3b这个组合原因很实际qwen2.5-3b对中文理解好3B参数在16GB内存的机器上跑得动而且资源占用可控。2.4 本地模型关联ollama部署和qwen2.5-3bollama的安装很简单curl -fsSL https://ollama.com/install.sh | sh装完先确认服务状态systemctl status ollama如果没在运行手动启动一下sudo systemctl enable --now ollama然后拉取模型ollama pull qwen2.5-3b拉完验证一下确保API能通curl http://127.0.0.1:11434/api/generate -d {model: qwen2.5-3b, prompt: 你好}这一步能省掉后续大量排查时间。如果curl都不通先查ollama服务是否监听在正确的地址上ss -tlnp | grep 11434如果监听地址是127.0.0.1而你的OpenClaw部署在Docker容器里那就会连接不上。所以再次说明我为什么建议源码方式部署就是因为这类网络链路问题在纯Linux环境里更容易排查。模型关联的另一个常见问题是OpenClaw配置里模型名必须和ollama里拉取的模型名完全一致。别写qw3或者qwen-2.5这样的缩写代码不做模糊匹配一字不差才能连上。我之前在这里卡了二十分钟才反应过来。3. 初始化失败、配置报错和高频坑位实录3.1 环境变量配置错误的连锁反应我在安装时犯过一个典型错误在~/.bashrc里把PYTHONPATH指向了一个旧项目目录导致OpenClaw启动时导入模块失败。现象很奇怪报错信息指向一个完全不相干的路径。排查思路是这样的echo $PYTHONPATH echo $PATH发现PYTHONPATH被污染后直接清掉这一行重新加载配置。这里也给一个通用建议OpenClaw这类框架对Python环境非常敏感建议全程使用虚拟环境不要直接装到系统全局。我在虚拟环境里装完后几乎再没遇到模块冲突问题。3.2 WSL2环境提示与Windows侧的历史包袱虽然这篇主打Ubuntu但还是要提一嘴WSL2因为不少读者是从Windows转过来的。如果你之前在Windows下用companion方式部署过尝试在Ubuntu下迁移时会看到一些残留提示比如“请在PowerShell中运行wsl --status”这类和环境检查相关的信息。这说明几件事第一Windows侧的WSL2虽然功能完整但在资源占用和IO性能上运行这类需要频繁读写配置文件的代理框架时体验不如原生Linux第二迁移到Ubuntu后建议删掉Windows侧的所有旧配置文件不要直接复制到Linux上用路径格式、权限位、换行符都不同直接复制只会带来新问题。3.3 编译和权限导致的问题我遇到过的另一个经典问题是GCC安装失败。报错一般是这样的The following packages have unmet dependencies: build-essential : Depends: gcc but it is not going to be installed原因多半是软件源缓存过期或者旧版本残留包冲突。解决办法sudo apt clean sudo apt update sudo apt install --fix-broken sudo apt install build-essential权限问题也很常见。OpenClaw的skill目录和日志目录在运行时需要读写权限如果你用sudo启动进程会产生大量root用户文件后续用普通用户改配置时会没权限写。我的习惯是全程用普通用户跑只有安装系统依赖时才用sudo。这样一来所有配置文件、日志、模型缓存都在我的用户目录下权限清晰备份和迁移都方便。3.4 SSH连接不上和网络配置的连带问题如果你和我一样是在一台常开的小主机上部署平时通过SSH远程操作那SSH连不上会直接影响后续所有工作。我的经验是先查服务状态sudo systemctl status sshd再查防火墙sudo ufw statusUbuntu默认防火墙是关闭的但如果你之前手动开过一定要记得放行22端口sudo ufw allow OpenSSH sudo ufw enable还有一个远程连不上的常见原因是安装系统时设置了固定IP但网卡名在你更换网络环境后变了导致路由不对。用ip addr看下当前网卡名在/etc/netplan/下的配置里做对应修改然后sudo netplan apply。4. 调优、skill配置和稳定运行实践4.1 让OpenClaw常驻后台systemd服务配置源码方式跑起来后我建议直接用systemd管起来比自己开一个终端挂着python main.py强得多。终端一关进程就没了开了screen或tmux还得惦记着完全没有必要。我的systemd服务文件长这样[Unit] DescriptionOpenClaw Service Afternetwork.target ollama.service [Service] Typesimple User你的用户名 WorkingDirectory/home/你的用户名/openclaw EnvironmentPATH/home/你的用户名/openclaw/venv/bin ExecStart/home/你的用户名/openclaw/venv/bin/python main.py --mode daemon Restartalways RestartSec10 [Install] WantedBymulti-user.target把这个文件放到/etc/systemd/system/openclaw.service然后sudo systemctl daemon-reload sudo systemctl enable --now openclaw服务跑起来后日常操作就变成sudo systemctl status openclaw # 查看状态 sudo systemctl restart openclaw # 重启 sudo journalctl -u openclaw -f # 实时看日志这里有一个比较重要的经验Afterollama.service的意思是等待ollama先启动避免OpenClaw启动时模型后端还没就绪导致连接失败。同理Restartalways让进程崩溃后自动拉起但RestartSec10留了10秒缓冲防止循环重启把日志刷爆炸。4.2 skill目录管理和自定义skill的写法OpenClaw的skill机制有点像手机上的快捷指令。每个skill是一个文件夹里面至少包含一个指令配置文件和一个处理逻辑文件。目录结构大致这样skills/ ├── weather/ │ ├── skill.yaml │ └── handler.py ├── reminder/ │ ├── skill.yaml │ └── handler.py └── search/ ├── skill.yaml └── handler.pyskill.yaml里定义了这个技能的触发词、参数说明和运行方式handler.py是对应的执行逻辑。这里有个细节skill的触发词和OpenClaw的默认系统指令不要冲突比如内置的“帮助”“退出”这类词就尽量别用作自定义触发词。自定义一个简单skill的体验还是不错的比如做一个开机问候name: greeting description: 启动时进行简短问候 trigger: on_event: startup keywords: [你好, 早上好] execute: handler.py对应的handler.py写几行Python逻辑就能跑。这里不展开写业务逻辑重点想说清楚的是整个OpenClaw的能力扩展就是靠这个目录结构完成的。理解了这一点后面在社区里看到别人的skill包下载后丢进目录、改下配置重启服务就能用。4.3 内存和显存调优的实际经验如果你和我一样用本地模型内存管理是个绕不开的话题。qwen2.5-3b量化版模型在纯CPU推理时大约吃4GB内存加上OpenClaw自身的常驻内存开销总共大概5GB出头。在16GB内存的机器上跑没问题但如果你同时跑多个浏览器窗口、开发IDE内存就会吃紧。我给几条实测有效的建议模型量化级别不要盲目追求低位数。用4bit量化已经是质量与性能的平衡点再往下压中文理解能力下降明显。ollama支持通过环境变量限制并发数在/etc/systemd/system/ollama.service的[Service]段加一行EnvironmentOLLAMA_NUM_PARALLEL1可以避免多个请求同时打进来时内存暴涨。如果使用NVIDIA显卡并且驱动正常ollama会自动检测到GPU并把模型加载进显存。跑ollama ps看一眼当前模型有没有显示GPU字样可以确认是否真的用上了GPU加速。4.4 我目前稳定的部署模板和使用心得最后把我当前稳定运行的整套配置模板放出来可以直接参考。Ubuntu 24.04Python 3.12虚拟环境Node.js 20ollama跑qwen2.5-3bOpenClaw以daemon模式由systemd托管。# 核心配置模板 config.yaml 关键部分 agent: name: openclaw mode: daemon language: zh-CN model: provider: ollama name: qwen2.5-3b base_url: http://127.0.0.1:11434 skill: dir: ./skills auto_load: true logging: level: INFO file: ./logs/openclaw.log再强调一遍几个我在实际操作中反复确认过的事项。日志路径建议单独建logs目录并且定期清理。OpenClaw长时间运行后日志膨胀很快我给systemd服务里加了LogRotate相关的配置如果你没加建议至少每周手动清理一次超过100MB的日志文件。配置文件修改后不需要重新编译但需要重启服务才能生效。sudo systemctl restart openclaw这一步别忘我之前改完配置后发现没生效以为是bug结果是忘了重启。最后OpenClaw的模型名、配置路径、skill目录路径只要有一处和实际情况对不上启动时不会直接崩溃但会在日志里报连接错误或加载错误。这类问题表面上看起来很复杂实际上90%都是路径或名称拼写问题。检查顺序永远是先看配置文件再看模型是否拉取成功最后看日志尾部报错信息。这个顺序我从第一次部署用到现在解决问题效率明显高出很多。就聊到这里。这套东西目前在我的小主机上已经连续跑了将近两周除了被我手动重启过没有一次是因为自己崩溃挂掉的。接下来我准备把之前Windows下的一些自动化流程迁移过来在skill里多写几个场景后面有心得再更新。