前后折腾了三天我终于把 OpenClaw 从一个“跑在 Windows 上时灵时不灵的玩具”变成了一台 Ubuntu 22.04 服务器上稳定运行的服务并且接入了阿里云的 Coding Plan让通义千问 qwen 系列模型成了它的默认后端。这个组合听起来不复杂实际动手时踩到的坑却相当密集Node 版本不匹配、WSL2 环境误判、百炼 API 的 base_url 写错、模型请求超时……每一个都能卡住半天。这篇文章是我完整跑完一轮后的实操记录不是官方文档复读。想长期在 Linux 服务器上跑 OpenClaw、并且把阿里云的模型能力接进来的朋友可以直接照着抄。1. 为什么把 OpenClaw 装在 Ubuntu 22.04 而不是 Windows 或 Docker1.1 OpenClaw 到底是个什么东西先花点时间说清楚 OpenClaw 的定位因为很多人第一次看到这个项目时会产生误解。OpenClaw 本身不是一个模型它不提供算力它是一个开源的 AI 代理框架。打个比方大模型是大脑负责理解和决策OpenClaw 是手脚和神经系统负责把决策变成实际动作——执行 shell 命令、读写文件、调用外部 API、运行 Skill。所以社区里那个高频问题“OpenClaw 只能用接入 API 的方式使用算力吗”就有了答案不是它也可以接本地模型比如 Ollama但接入云端 API 是最省事、效果最稳定的方式尤其是当你需要跑 qwen-max 这个级别的强模型时。理解了这一点你就会明白部署 OpenClaw 的重点不在模型本身而在“怎么把模型端点接进来、怎么让它安全地操作你的机器”。1.2 我为什么选择 Ubuntu 22.04 LTS这个选择不是拍脑袋的。首先是生命周期22.04 LTS 的支持周期到 2027 年意味着系统不会突然搞大版本升级把你的服务打断。其次是软件生态OpenClaw 这类 Node.js 项目在 Ubuntu 上安装原生依赖非常顺Python、GCC、Node 都能用 apt 或官方脚本干净地装好。相比之下Windows 上有两个大坑。一是 PowerShell 和 CMD 的语法和 Bash 差异很大OpenClaw 的 Skill 大多是为 Linux shell 设计的迁移过来要改很多东西二是 Windows 版围绕 WSL2 做了一些“安全检查”我在社区里看到大量“openclaw 无法安全验证 WSL2 环境”的求助帖自己也踩过后面专门讲。1.3 裸机部署还是 Docker 部署我也认真考虑过 Docker。Docker 的好处是干净、可复现环境搞坏了删容器重来。但对 OpenClaw 这种需要操作宿主机资源的 agent 来说Docker 反而制造了新的问题Skill 里的脚本默认访问不了宿主机的文件容器内执行 systemctl、docker 这类命令需要额外授权网络模式配置不对模型 API 和本地服务都会连不上。我的结论是如果你是个人使用机器也只有这一台在跑服务裸机部署最省心。下面这张表是我当时的选型依据部署方式资源占用Skill 访问本地资源维护难度推荐场景裸机部署低直接访问低个人长期自用、单机服务Docker中需要挂载目录、特权模式中团队标准化交付、多实例隔离Windows / WSL2中高路径转换麻烦、权限问题多高只有 Windows 且不想装双系统2. 部署前准备Node 版本、系统依赖与镜像源一个都不能少2.1 先用 nvm 装 Node 20别用 apt 的默认版本OpenClaw 对 Node 版本有硬性要求官方文档写的是 18 以上但我实测下来 Node 20 LTS 最稳。Ubuntu 22.04 的 apt 源里默认的 nodejs 版本比较老直接 apt install nodejs 大概率会踩版本坑。正确做法是先装 nvm再用 nvm 装 Node 20。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm alias default 20 node -v npm -v这里有一个容易被忽略的细节nvm alias default一定要执行否则你新开一个 SSH 终端后 node 命令会消失很多新手在这一步就开始怀疑人生。2.2 系统依赖build-essential 和字体不能少OpenClaw 的 npm install 过程会编译一些原生模块最常见的是 node-gyp 参与构建的包。如果系统里没有完整的编译工具链你会看到一堆gyp ERR! stack Error: not found: make之类的报错。所以先把基础依赖装齐sudo apt update sudo apt install -y git curl build-essential ca-certificates fonts-noto-cjkfonts-noto-cjk这个包容易被忽略但很重要。因为它接入通义千问之后控制台输出中文内容的概率极高缺字体的话日志里全是方块字排查问题时会非常痛苦。2.3 网络源优化apt 和 npm 都值得配如果你的服务器在国内官方源拉包的速度可能让人崩溃。apt 源可以替换成国内镜像源在/etc/apt/sources.list里把archive.ubuntu.com替换为你信任的镜像地址然后sudo apt update。npm 同样可以配置 registrynpm config set registry https://registry.npmmirror.com需要注意镜像源只是加速下载不会改变任何软件行为放心用。判断是否需要配置的标准很简单如果npm install长时间停在某个包上纹丝不动就配如果几十秒就装完了不配也行。3. 从零跑通 OpenClaw拉代码、装依赖、把配置写对3.1 安装过程clone 下来npm install 到底OpenClaw 的安装方式根据你拿到的版本略有不同但主线流程是拉代码、装依赖、初始化配置。mkdir -p ~/apps cd ~/apps git clone 你的 openclaw 仓库地址 openclaw cd openclaw npm install如果仓库里有build脚本记得执行npm run build。第一次 npm install 的输出会特别长中间可能还有一些 warning只要不是ERR!就让它跑完千万别中途 CtrlC。我见过有人因为嫌输出多而中断安装结果 node_modules 半残后面反复出问题。3.2 初始化配置配置文件里每项都是干什么的安装完成后OpenClaw 会引导你创建一个配置文件。不同版本的默认路径可能不同我这边生成的是~/.openclaw/config.json。下面是一个最简配置的参考{ provider: dashscope, model: qwen-plus, api_key: sk-你的百炼key, base_url: https://dashscope.aliyuncs.com/compatible-mode/v1, skill_dir: ~/.openclaw/skills, port: 8080, system_prompt: 你是部署在服务器上的自动化助手所有操作需要先解释再执行。 }逐个说下这些字段的意义。provider是模型供应商标识OpenClaw 靠它决定走哪套适配逻辑model是具体的模型名必须是后端平台真实的模型 IDapi_key是调用模型的凭证base_url是 API 网关地址这个最容易写错后面接入阿里云时我会重点讲skill_dir是 Skill 脚本的存放目录port是 OpenClaw 自己对外服务的监听端口system_prompt决定了这个 agent 的行为基调。提示配置文件是 JSON 格式多一个逗号都会导致启动失败。写完用jq . ~/.openclaw/config.json校验一下语法最稳妥。3.3 首次启动怎么判断它真的跑起来了启动命令一般是npm start或者看 README 里指定的入口文件。启动成功的标志不是“没有任何报错”而是日志里出现类似Server listening on port 8080的信息。启动后先别急着上复杂任务让它回答一个最简单的问题比如“用一句话介绍你自己”。如果它能正常返回说明模型链路通了。如果失败最常见的三个原因端口被占、依赖没有装全、配置文件 JSON 语法错误。端口被占用就换一个依赖问题回到第 2 节补JSON 问题用 jq 检查。4. 接入阿里云 Coding Plan百炼端点、API Key 与模型选择4.1 先搞清楚 Coding Plan 里到底有什么很多人以为 Coding Plan 是一个类似“OpenClaw 插件”的东西装上就能用。其实不是。阿里云 Coding Plan 本质上是一个面向开发者的权益套餐里面包含百炼平台的模型 API 调用额度、通义灵码这类 AI 编程工具的使用权益以及一些云产品代金券。对我们部署 OpenClaw 来说真正要被消费的是百炼平台的模型 API。所以整个接入动作可以理解为把阿里云百炼当成一个兼容 OpenAI 协议的模型供应商配置进 OpenClaw。Coding Plan 提供的就是这套额度的来源套餐生效后你在百炼平台就能创建 API Key 并调用 qwen 系列模型。4.2 开通百炼、创建 API Key、选模型完整链路分三步。第一步登录阿里云进入百炼控制台按提示开通模型服务。第二步在控制台创建一个 API Key或者叫 DashScope Key。第三步在模型广场确认你要用的模型 ID。我建议的默认选择是qwen-plus性价比和稳定性比较均衡。不同场景可以参考下面这张表模型 ID特点适合场景qwen-turbo响应快、价格低高频简单任务、批量处理qwen-plus能力均衡默认选择日常自动化qwen-max推理最强、价格高复杂代码生成、长链路规划4.3 配置到 OpenClawcompatible-mode 端点为什么重要把第 3 节的配置模板换成百炼的真实参数就是最终的接入配置{ provider: dashscope, model: qwen-plus, api_key: sk-你的百炼key, base_url: https://dashscope.aliyuncs.com/compatible-mode/v1, skill_dir: ~/.openclaw/skills, port: 8080 }关键就在base_url。阿里云百炼同时提供了原生 DashScope API 和 OpenAI 兼容模式强烈建议使用兼容模式也就是带/compatible-mode/v1的那个地址。原因很简单OpenClaw 底层大量依赖 OpenAI 的 SDK 和消息格式兼容模式能直接复用原生协议还需要额外的适配没必要给自己找事。注意模型名是大小写敏感的qwen-plus是全小写不要手滑写成大写。API Key 也一样不要带多余空格。4.4 用 curl 验证链路再让 OpenClaw 跑真实任务配完之后先别急着打开 OpenClaw用 curl 直接打一下百炼端点确认 Key 和模型名都没问题curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer sk-你的百炼key \ -H Content-Type: application/json \ -d {model:qwen-plus,messages:[{role:user,content:你好这是一个连通性测试}]}如果返回了带choices的 JSON说明链路通。然后启动 OpenClaw给它布置一个真实任务比如“写一个自动备份 /var/log 的 shell 脚本并解释每一步在干什么”。观察三个指标首字延迟、token 消耗、是否触发限流。如果出现rate limit之类的报错先检查 Coding Plan 的额度有没有生效再确认模型计费方式。4.5 安全建议别把主账号 Key 写死在配置文件里这一点值得单独说。配置文件里的api_key如果直接写明文一旦配置文件泄露等于把整个模型额度交出去。建议的做法是在 OpenClaw 的启动脚本里用环境变量注入密钥配置文件里引用${OPENCLAW_API_KEY}这类占位符。另外如果阿里云账号有多人协作建议创建 RAM 子用户只授予 DashScope 相关权限而不是把主账号的 Key 到处粘贴。5. 踩坑实录四条最容易卡壳的排查链路5.1 “WSL 环境无法安全验证”到底是怎么回事这是我看到讨论热度最高的问题“openclaw 无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status”。我当时在 Windows 上第一次遇到时老老实实去 PowerShell 执行了wsl --status系统显示 WSL 已启用但 OpenClaw 的 Windows Companion 还是报同样的错误。完整的排查链路是这样的先在 PowerShell 里执行wsl -l -v确认你的 Linux 发行版版本号是 2然后进入发行版执行uname -a确认内核版本最后回到 OpenClaw 看它检测的是哪个发行版路径。我后来发现问题出在 Windows 侧伴生程序和我实际使用的 WSL 发行版路径对不上并不是 Linux 系统本身的问题。这个坑的根源在于“身份混淆”你在 PowerShell 里执行wsl --status检查的是系统级 WSL 功能而 OpenClaw 检查的是某个特定发行版的运行环境。我的最终解决方案是放弃 Windows 部署直接在一台 Ubuntu 22.04 服务器上重新部署。如果你也是想长期跑服务建议一步到位别在 Windows 和 WSL 之间来回横跳。5.2 node-gyp 编译失败先补编译链别急着换 Node 版本npm install 过程中报gyp ERR! build error时第一反应往往是“是不是 Node 版本不对”然后去切换 Node 版本结果越切越乱。实际上大多数编译失败是因为系统缺 Python 和编译工具链。sudo apt install -y python3 python3-pip build-essential cd ~/apps/openclaw rm -rf node_modules package-lock.json npm install清理重装这一步很重要因为上次失败的 node_modules 里可能残留了不完整的编译产物。注意顺序先补依赖再清缓存最后重装。如果你在空跑时看到gyp ERR! stack Error: not found: make那基本就是 build-essential 没装。5.3 模型请求超时先 curl 测端点再检查超时配置接入百炼后我遇到过一次诡异的现象简单问题秒回复杂问题大概率超时。一开始怀疑是网络问题后来用 curl 直接测同样的请求发现端点响应是正常的问题出在 OpenClaw 的请求超时时间配置上。qwen-max 这类模型在长任务场景下首字输出可能超过默认的 30 秒而 OpenClaw 里有独立的 timeout 配置项默认值对复杂任务偏保守。排查顺序建议是先 curl 确认模型本身能通再看配置文件里的timeout字段如果是长任务场景直接调到 120 秒。网络连通性用curl -v看连接建立的时间模型首字延迟用curl -w看总耗时这两者能帮你快速定位是网络层还是模型层的问题。5.4 卸载重装怎么才算卸干净社区里不少人问“怎么卸载 openclaw”。如果你只是删了项目目录配置文件、Skill、日志都还在重新安装时旧配置会干扰新版本。我重装时的完整步骤是这样# 如果是 systemd 方式启动的服务先停服务 sudo systemctl stop openclaw # 兜底杀掉所有残留进程 pkill -f openclaw # 备份配置和 Skill重要 cp -r ~/.openclaw ~/.openclaw.bak # 删除项目目录和配置目录 rm -rf ~/apps/openclaw ~/.openclaw备份这步千万别省。Skill 是你自己积累的资产配置文件里存着 API 端点信息丢了要重新折腾一遍。6. 部署完成之后Ollama 本地兜底、Skill 扩展与服务联动6.1 装一个 Ollama 做离线兜底既然社区里很多人关心“OpenClaw 能不能不靠 API 算力”我就顺手把本地模型这条线也讲清楚。在同一台 Ubuntu 22.04 上装 Ollama 非常快curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b然后在 OpenClaw 配置里加一个新的 provider 指向http://localhost:11434/v1模型名写qwen2.5:3b。本地模型的优势是零费用、断网可用、隐私数据不出机器劣势是能力明显弱于 qwen-max。我的用法是日常跑自动化任务用百炼 qwen-plus测试 Skill 语法或者网络抽风时切到本地模型兜底。6.2 写第一个 Skill让 OpenClaw 定时巡检磁盘OpenClaw 的 Skill 机制值得单独体验一下。Skill 不是传统意义上的插件它更像是“给模型看的一份操作手册”。以磁盘巡检为例在~/.openclaw/skills/disk_alert/下创建两个文件SKILL.md check.shSKILL.md里写清楚这个 Skill 的触发方式和使用说明# 磁盘巡检 触发词检查磁盘、磁盘空间 作用执行磁盘空间检查当使用率超过 80% 时给出警告。 用法用户说“检查磁盘”时运行 check.sh 并解读输出。check.sh里写实际逻辑#!/bin/bash threshold80 current$(df / | awk NR2 {print $5} | sed s/%//) if [ $current -gt $threshold ]; then echo 警告根分区使用率已达 ${current}%请及时清理。 else echo 磁盘状态健康当前使用率 ${current}%。 fi给check.sh加执行权限chmod x check.sh。之后你只要在对话里说“检查磁盘”OpenClaw 就会自动匹配到这个 Skill 并执行。这个模式的价值在于你不需要每次把需求描述得很详细它有一本“说明书”可以照着干活。6.3 联动阿里云其他服务的最小思路把百炼接进来之后其实你已经有了一个能操作服务器、能调用云 API 的自动化入口。顺着这个思路可以把 OSS 文件同步、短信通知、RDS 状态查询都包成 Skill让 OpenClaw 统一调度。我的核心建议是权限隔离给每个 Skill 分配最小权限生产环境的 Key 用环境变量注入别把所有云资源权限都暴露给同一个 agent。部署完成后我最大的感受是OpenClaw 这类工具真正的门槛不在安装而在怎么把它接进你已有的云资源和日常任务流。把百炼接上之后它就从一个“能聊天的命令行玩具”变成了能定时巡检、能写脚本、能查日志的服务器管家。如果你也在 Ubuntu 22.04 上折腾建议先把 Node 版本和配置文件里的 base_url 这两个最不起眼的点搞定能少走很多弯路。