1. OpenClaw 是什么为什么装在 Ubuntu 虚拟机里1.1 OpenClaw 解决的是什么问题OpenClaw 本质上是一个连接型 AI 代理框架。你可以把它理解成一套“AI 中控台”它负责接收来自不同平台的消息把消息交给配置好的大模型去处理再根据模型返回的结果触发相应动作最后把回复传回原平台。它不是一个简单的聊天机器人而是可以通过 channel 同时对接多个入口比如 Microsoft Teams、本地终端、Obsidian 这类知识库工具也可以接入不同的大模型服务OpenAI 兼容接口、千问这类都能配。这套设计解决了一个很实际的痛点。以前每个平台都要单独接一个机器人每个机器人的逻辑还不太一样维护起来相当痛苦。OpenClaw 把消息接收、模型调用、工具执行这三层统一起来配置一次模型和工具所有 channel 就能共享同一套行为逻辑。再加上它有 session 机制每个会话能保持上下文用起来更像一个有记忆的助手而不是一问一答的接口封装。对于一个人要同时维护多个消息入口的场景这一套框架能把重复工作大幅压缩。1.2 为什么选 Ubuntu 全新虚拟机我用虚拟机而不是物理机来部署原因比较实际。OpenClaw 依赖的东西不少包括 Node.js、Python、Git 和各种系统库如果直接装在常用主力机上时间一长很容易把系统环境搞乱。虚拟机的好处是隔离性很强随便折腾坏了就回滚快照不会影响日常使用的机器。我这次用的是 VMware Workstation配合 Ubuntu 22.04 LTS 镜像是非常稳妥的组合。虚拟机还有个额外好处就是方便做“干净环境验证”。因为 OpenClaw 的安装脚本和手动部署方式对系统状态要求不太一样如果在一台已经装了一堆东西的系统上部署经常分不清问题是依赖冲突还是配置写错了。用全新虚拟机从零开始走一遍每个依赖都是明确安装的出问题时可以精确定位。这也是我建议新手学 OpenClaw 时优先选择虚拟机的原因。后面所有步骤我都按照“全新安装 Ubuntu → 基础环境配置 → 部署 OpenClaw → 接入渠道”的顺序来写。2. 安装前准备VMware、Ubuntu 镜像与虚拟机参数2.1 需要准备的材料清单在动手之前先把要用的东西列清楚。我自己的环境是宿主机 Windows 11VMware Workstation 17虚拟机里装 Ubuntu 22.04 LTS这样的组合跑 OpenClaw 很流畅。材料说明VMware Workstation我用的是 17 版本16 也可以操作基本一致Ubuntu 22.04 LTS 镜像推荐 64 位 desktop 版本安装和配置最省事宿主机内存至少 8GB虚拟机建议分 4GB宿主机要留余量网络虚拟机使用 NAT 模式宿主机能上网就行SSH 客户端可选远程操作时会很方便这里单独说一下版本选择。OpenClaw 对 Ubuntu 20.04 和 22.04 都能跑但我更推荐 22.04 LTS。原因是 22.04 自带的 Python 3.10、系统库版本都比较新安装依赖时能少折腾。要是用 20.04后续有些工具需要自己加源或者编译反而多出不少步骤。至于要不要用 server 版我的建议是如果只是跑服务server 版更省资源但如果你还需要打开浏览器看日志、偶尔用桌面工具desktop 版更友好。我这里选的是 desktop。2.2 新建虚拟机时需要注意的参数在 VMware 里新建虚拟机通常选“典型”向导就可以但有几个关键参数必须手动确认。第一是操作系统类型要选 Ubuntu 64 位。如果误选成 32 位后面装软件和内核模块时会遇到一堆兼容问题。第二是磁盘容量建议至少给到 40GB。OpenClaw 的依赖文件、日志、模型缓存加在一起20GB 会很紧张。第三是内存至少分配 4GB。只给 2GB 的话后面同时跑 Node 服务和模型请求时会频繁卡顿甚至直接内存不足。网络模式保持默认 NAT 就行。NAT 模式下虚拟机通过宿主机共享网络不需要手动配 IP对新手最友好。如果之后想从宿主机直接访问虚拟机里的 Web 接口再用桥接模式或配置端口转发这里先不展开。建好虚拟机后先别急着启动系统。点“编辑虚拟机设置”在“处理器”里勾选虚拟化 Intel VT-x/AMD-V硬件虚拟化开启后安装和更新速度会明显提升。再把“显示”里的 3D 加速打开Ubuntu 桌面体验会好一点。做完这些配置挂载 Ubuntu ISO 镜像然后开机安装。2.3 Ubuntu 安装过程中的几个关键点安装 Ubuntu 时最容易出问题的有三处。第一处是“安装类型”。新手容易直接选“清除整个磁盘”这在虚拟机里没问题但一定要看清楚磁盘是否指向虚拟机的虚拟磁盘千万不要误选到宿主机硬盘。稳妥做法是选“自定义”手动分区。我一般使用整个磁盘并开启 LVM后续扩容方便快照兼容性也好。第二处是用户名和密码。建议用简单好记的用户名不要带空格和特殊字符。后面很多服务配置和 systemd 文件里都会用到用户名太复杂会增加转义麻烦。第三处是安装过程中是否下载更新。如果你网速一般建议选“最小安装”先把系统跑起来进系统后再手动更新软件源。否则安装时下载几百个更新包会拖慢整个流程。系统装完后重启进入 Ubuntu第一件事就是拍快照。因为接下来要换源、更新、装依赖一旦操作失误可以快速恢复到干净状态。我给这个快照命名为 fresh-ubuntu-installed后面部署完还要再拍一个。3. Ubuntu 基础环境配置依赖不装齐OpenClaw 根本起不来3.1 先换软件源再做系统更新全新安装的 Ubuntu 默认软件源指向官方服务器下载速度不太稳定所以第一步是换成国内镜像源。这里以阿里云源为例Ubuntu 22.04 对应的操作如下。执行前先备份原文件这是一个任何时候都适用的好习惯。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 apt update sudo apt upgrade -y这里有个坑值得提醒如果不提前备份手滑改坏了源文件apt update 会一直报错到时候只能从恢复模式去改非常麻烦。备份一下成本极低别省这一步。换完源后顺手把常用工具装上sudo apt install -y curl wget vim net-tools ca-certificates这些不是 OpenClaw 的硬依赖但排查问题时会频繁用到。curl 用来测接口wget 用来下载文件vim 用来改配置net-tools 里的 ifconfig 查 IP 比 ip addr 直观建议都装上。3.2 Python 和 Node.js 版本到底怎么选OpenClaw 的运行环境主要依赖 Python 和 Node.js。Ubuntu 22.04 自带 Python 3.10通常够用但需要确认 python3 命令指向正确并且 pip 可用。Node.js 则推荐 18 以上我这边直接用 Node.js 20 LTS。原因很简单OpenClaw 的依赖树里有些包要求 Node 18 以上低于这个版本在 npm install 阶段就会报 engine 不满足直接装不上。Node.js 20 的安装方式我用的 NodeSource 源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs装完检查版本node --version npm --version如果 npm 版本太旧先升级一下避免后续安装 OpenClaw 依赖时出现 peer dependency 解析失败sudo npm install -g npmlatestPython 这边建议安装 python3-venv 和 python3-pip。OpenClaw 的 Python 侧组件通常希望装进独立的虚拟环境而不是直接装到系统全局。用 venv 隔离后跑坏了直接删掉重建不影响系统环境。sudo apt install -y python3-venv python3-pip这一步很多人会忽略但如果你直接用系统全局 Python 安装项目依赖几个项目之间很容易相互覆盖版本后面追查问题会非常痛苦。3.3 环境变量、编码和路径的隐性坑Ubuntu 默认的 locale 通常是 C.UTF-8大多数情况没问题但如果你安装系统时选了中文界面有些日志里的中文会乱码甚至影响部分 Python 依赖的编码处理。为安全起见建议统一设置成 en_US.UTF-8。sudo apt install -y locales sudo locale-gen en_US.UTF-8 sudo update-locale LANGen_US.UTF-8改完 locale 后重启终端让配置生效。单独把这个问题拿出来说是因为很多人部署 OpenClaw 后遇到 UnicodeDecodeError 或者日志里中文变成问号排查到最后才发现是 locale 问题。提前处理好后面少很多莫名其妙的现象。环境变量方面我习惯把 ~/.local/bin 确认在 PATH 中。很多工具默认安装在用户目录下的 bin 目录如果不在 PATH 里命令行会提示 command not found实际上程序已经装好了。把下面这行追加到 .bashrc 里echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc还有一个容易忽略的点如果后面要把 OpenClaw 注册成 systemd 服务运行命令时要写绝对路径。比如 node 的绝对路径可以通过which node查不要想当然用相对路径否则服务启动时会报找不到命令。4. OpenClaw 本体安装脚本部署还是手动拉代码4.1 安装方式怎么选OpenClaw 的部署方式有两种常见路径一种是用现成的安装脚本一种是手动拉取代码库再安装依赖。对于全新虚拟机环境我优先推荐脚本方式因为它会把系统依赖检查、目录初始化、命令软链都做好省去手动踩雷。手动方式更适合需要改源码二次开发的场景新人没必要走这条路。在跑安装脚本之前先确认环境就绪。最简单的验证方式git --version python3 --version node --version npm --version这四条命令如果能正常输出版本就可以继续。任何一个报 not found先回头补装对应组件不要带着缺失环境直接跑脚本否则出错时很难判断是脚本问题还是环境问题。OpenClaw 的安装脚本通常要做这些事创建数据目录、检查系统架构、拉取核心代码、安装 Python 和 Node 依赖、生成默认配置文件。整个过程耗时取决于网络情况一般几分钟到十几分钟。脚本执行期间不要断开终端也不要 CtrlC耐心等它跑完。如果长时间卡在下载阶段先确认网络是否正常而不是反复重启脚本。4.2 初始化配置文件和第一个 Agent脚本安装完成后正常情况下会在用户目录下生成 OpenClaw 的数据目录里面包含默认配置文件。首次启动时程序会引导你初始化。这里有一个特别重要的概念agent。OpenClaw 里的 agent 可以理解为一个逻辑会话单元每个 agent 可以绑定不同的模型、系统提示词和 channel 偏好。初始化时创建的 agent 就是默认 agent之后所有请求如果不显式指定 agent都会走这个默认配置。配置模型这一步最关键。OpenClaw 需要指定模型提供商和对应的 API Key。它兼容 OpenAI 风格的接口所以像千问这类提供 OpenAI 兼容访问点的服务也可以接入。配置时要注意 base_url、model 名称和 api_key 三项不能填错。很多报错都集中在 base_url 多了一个斜杠或者路径不对这种错误从简单日志里不一定看得出来建议复制粘贴时逐字符检查。这里给一个简化版的配置示例帮助你理解结构agent: default: model: qwen-max api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: your-api-key channel: cli实际配置结构可能因版本不同有差异但思路一致。配置完模型后先不要急着接 Teams 或 Obsidian先用命令行 channel 跑一次简单对话确认模型调用链路是通的。如果 CLI 都返回不了正常结果说明配置有问题再接外部渠道只是浪费时间。4.3 启动服务并验证运行状态启动方式通常是直接运行 openclaw 命令或用脚本启动。我建议第一次启动时选择前台模式这样能直接看日志。如果命令启动后没有报错终端里会显示服务监听状态、agent 标识信息和可用 channel 列表。此时用最简单的方式测试在 CLI channel 里输入一句“你好”看模型是否正常返回。我实测时遇到过一次返回超时原因其实是 model 名称写错了。服务本身没报错但模型请求一直失败这类问题要看 API 返回码或更详细的 debug 日志才能定位。验证通过后再考虑把 OpenClaw 注册成 systemd 服务让它后台常驻。这样虚拟机重启后服务能自动拉起不用每天手动去启动。systemd 配置的关键是 ExecStart 写绝对路径WorkingDirectory 指向数据目录User 写成当前用户这样权限和路径都不会出错。5. 核心配置进阶模型、Channel 与插件5.1 多模型配置和模型提供商选择OpenClaw 支持同时配置多个模型并在不同 agent 或 channel 之间切换。这样做的价值在于成本控制简单对话用快模型复杂任务用更强模型响应时间和消耗都能优化。配置多个模型时最怕把 api_key 配到错误的 provider 段里。建议每个模型单独建一个 provider 配置段命名清晰比如 qwen、gpt、ollama 等然后在 agent 的 model 字段里引用。你会发现清晰的配置结构能省下大量排查时间。我踩过的一个坑是在配置千问兼容接口时有些版本要求把模型名写成 qwen-plus有些版本又要求带日期后缀比如 qwen-max-2024-xx-xx。建议去模型服务商文档确认最新的可用模型标识别照抄旧教程。另外如果本地装了 Ollama也可以把它作为 provider 接入只需要把 base_url 指向本地 11434 端口。这样即使没有外部模型服务也能跑基础功能适合内网环境或隐私要求高的场景。5.2 Channel 选择CLI、Teams、Obsidian 的区别OpenClaw 的 channel 机制是它最有价值的部分。每个 channel 代表一个消息入口负责把对应平台的消息转换成内部会话消息并把回复发送回去。常见 channel 有 CLI、Microsoft Teams、Obsidian 等。选择 channel 前要理解几个概念channel 是消息入口不承担模型逻辑多个 channel 可以同时启用共享同一个 agent 配置每个 channel 需要独立的凭证配置接入 Microsoft Teams 时核心是创建一个 bot 服务然后在 OpenClaw 配置里填入 bot id、bot password 和 tenant id。Teams channel 启动后通常会生成一个消息端点 URL需要在 Teams 应用配置里把消息回调地址指向这个 URL这样 Teams 平台才会把用户消息转发给 OpenClaw。这个链路有一个常见问题本地虚拟机如果不做端口转发外网根本访问不到回调地址。所以要把虚拟机端口映射到宿主机或者在公网可达的服务器上部署。Obsidian channel 的思路侧重点不同它更多是双向同步。OpenClaw 可以读取 Obsidian 库中的笔记作为上下文也可以把对话记录或任务结果写入指定笔记文件。配置时主要确认 vault 目录路径和允许读写的目录白名单避免程序读取到机器上所有 markdown 文件。安全边界很重要别图省事直接把整个 home 目录暴露给它。CLI channel 是最简单的适合调试。它把终端当作对话入口不需要回调地址和额外凭证。所以整个部署流程里我建议先把 CLI channel 作为调试起点跑通后再逐步接入外部平台。5.3 处理 session file locked 报错部署 OpenClaw 时我遇到最典型的一个报错是agent failed before reply: session file locked (timeout 60000ms)这个报错的意思是 agent 在处理请求时尝试读取或写入某个 session 文件但该文件始终处于锁定状态并且在 60 秒内没有解除锁定。常见原因主要有四个。第一个是进程重复启动。如果你同时启动了多个 OpenClaw 进程它们会争夺同一个 session 文件锁后启动的进程会一直等待锁释放。排查时执行ps aux | grep openclaw如果发现多个进程全部停掉然后只启动一个。第二个是异常退出留下的锁文件。上次进程被强制 kill 时没来得及清理锁文件下次启动就会卡在这个文件上。处理方式比较简单找到 session 目录下的 lock 文件删除后再启动。第三个是文件权限问题。某个 session 文件的所有者或读写权限不对导致进程无法获取锁。解决方法是确认运行 OpenClaw 的用户和目录所有者一致必要时用 chown 修改属主sudo chown -R youruser:youruser ~/.openclaw第四个是多个 agent 同时读写同一个 session 目录。个别版本对并发处理能力有限当多个 channel 同时给 agent 发消息时会产生竞争。这种情况下可以给不同 agent 指定独立的 session 目录或者降低并发请求频率。这个报错的排查思路其实很典型。遇到问题不要只盯着 timeout 字面意思要往“谁在锁文件”“为什么锁没释放”两个方向去查。我个人的排查顺序是先看进程再删锁再查权限最后考虑并发。6. 常见问题速查与部署避坑清单6.1 部署时的典型错误一览我这次部署中遇到的错误整理成表格方便之后对照排查。错误现象可能原因处理方式command not found: openclawPATH 中没有包含安装目录将 openclaw 所在目录加入 PATH 或创建软链npm ERR! engine mismatchNode.js 版本过低升级到 Node.js 18/20 LTSpython3-venv 创建失败缺少 python3-venv 包sudo apt install python3-venvmodel request timeoutbase_url 或模型名配置错误核对 API 兼容地址和模型标识session file locked进程重复、锁残留或权限问题按上一节顺序逐步排查Teams 收不到消息回调 URL 未配置或端口不可达确认 endpoint 地址可以被正常访问这里提醒一句不要看到 timeout 就觉得是网络问题。本机部署时很多 timeout 其实是锁等待或进程卡顿导致的。先用局部日志定位再看外部因素顺序不能反。6.2 虚拟机快照与备份建议整个部署过程中建议最少拍两次快照。第一次在 Ubuntu 系统刚装完时此时没有任何多余配置是最干净的基底。第二次在 OpenClaw 完成初始化、CLI channel 验证通过后这时的环境已经处于基本可用状态。之后不管怎么折腾渠道和插件最多回滚到第二次快照不用从零重来。备份方面OpenClaw 的配置目录是核心资产包含 agent 配置、会话记录和渠道凭证。定期把整个配置目录打包下载到宿主机成本很低但保护意义很大。否则虚拟机磁盘损坏或误删配置重建环境和重新配置渠道凭证的成本会非常高。6.3 我的实操经验与建议最后分享几条实操经验。配置阶段别一上来就接 Teams。虽然 Teams 看起来最酷但排查链多了一层一旦有问题很难定位。先用 CLI 把模型链路跑通再一步步加渠道每加一个渠道都单独验证这样可以快速锁定问题出在哪个环节。多用快照。很多人觉得快照占空间实际上虚拟机的快照只有在后续写入时才会有增量开销。你拍完快照再部署如果成功就继续跑如果失败就回滚快照本身不会明显拖慢速度。有了快照兜底你会更敢动手改配置。还有一个建议是日志优先于盲目搜索。OpenClaw 的日志输出已经提供了足够信息大多数问题在日志里都有明确线索比如 session 锁、依赖缺失、配置项不合法等。与其把报错原文复制到搜索引擎里翻旧教程不如先看当前版本的日志文件。OpenClaw 这类框架更新较快版本差异会带来配置结构上的变化部署前最好看一遍当前文档确认配置格式。旧教程可以参考思路但不要直接照抄否则版本一升级很多参数就失效了。我个人在实际使用中体会最深的一点是虚拟机的隔离环境特别适合这种多依赖、多渠道的框架出问题可以大胆回滚完全不用心疼。我这次在 Ubuntu 22.04 上完整跑通之后稳定性相当不错后面还准备把定时任务和本地脚本接进去让 OpenClaw 不只是被动回复消息还能主动处理一些日常杂活。