用了两天时间总算把OpenClaw在Ubuntu 22.04上完整跑通了。期间踩了十几个坑从agent failed before reply: session file locked (timeout 60000ms)这种让人摸不着头脑的消息到环境变量写错把整个系统命令搞挂再到接飞书时消息被截断每一步都让人头大。写这篇文章主要是想把整套安装、配置、排错过程梳理清楚给准备在Ubuntu上部署OpenClaw的朋友一份能直接照着做的实操记录。先说结论OpenClaw 本质是一个把大模型能力接到各种聊天平台上的私有AI代理框架你可以把它理解成一个万能消息中转站——飞书、Teams、Telegram、Obsidian 里的消息进来它负责调用你配置好的大模型处理再把结果回复到对应渠道。在 Ubuntu 上安装并不复杂但坑主要集中在运行环境的版本匹配、账户权限、系统服务托管和各个 channel 的密钥配置上。这篇博文我会按照自己的实际部署顺序来写从架构拆解开始一路到最后的 systemd 常驻运行争取让你少走弯路。1. 装之前先搞懂一件事OpenClaw 在 Ubuntu 上到底跑的是什么很多人在 Ubuntu 上装 OpenClaw 一上来就报错根本原因不是命令敲错而是没搞明白这个项目由几部分组成。搞清楚架构之后再动手出问题时排查的思路会清晰很多。1.1 Agent、Channel、Skill 这三件套的关系OpenClaw 的核心可以拆成三层。最底层是 Agent 本身它负责调用大模型、管理对话历史、决定下一步动作中间层是 Channel也就是消息渠道飞书、Teams、Discord 这些平台上的事件都会通过 Channel 转换成内部消息最上层是 Skill技能和 Script脚本用来扩展 Agent 的能力比如让它能搜索网页、读写本地文件、调用外部 API。我刚开始犯了个错误以为 OpenClaw 只是某个模型的一层壳装好就能直接用。实际不是它要求你先配置好 Agent 的模型供应商再配置至少一个 Channel这两者缺一不可。模型供应商决定 Agent 的脑子Channel 决定你从哪儿跟它对话。Ubuntu 上安装做的事情说白了就是把这两层接起来再让它们跑得稳。1.2 消息从飞书发到 Agent 再回复回来中间发生了什么以飞书为例一条消息的完整链路大概是飞书服务器把用户消息推送到 OpenClaw 在 Ubuntu 上监听的 Webhook 端口OpenClaw 的飞书 Channel 收到事件后会转换身份并交给 Agent 处理。Agent 带着上下文调用大模型接口得到回复后再通过飞书 API 发回聊天窗口。链条里任何一环断了表现都可能很奇怪。比如端口没监听飞书那边显示消息发送失败Agent 没配置模型飞书里消息发过去半天没反应session 文件被锁住直接报agent failed before reply。所以排查时记住一个顺序先从 OpenClaw 的日志看消息有没有进来再看 Agent 有没有真的去调用大模型最后看回复有没有发出去。大部分问题都出在这三段交接处。1.3 为什么 session 文件会成为最大的坑session file locked (timeout 60000ms)这个报错网上相关讨论特别多。它的成因很简单OpenClaw 会把每个对话的状态保存到本地 session 文件里如果上一个对话进程还没来得及释放文件锁或者文件权限不对新的请求就会一直等锁等 60 秒超时后直接报错。我遇到这个报错时OpenClaw 进程是 root 启动的而后来手动测试时用了普通用户session 目录的属主不一致普通用户根本拿不到锁。解决办法也不是改什么高深配置把 session 目录的属主统一一下就行。这类问题等你装多了就会发现根因往往特别朴素。2. 基础环境准备Node 版本、Docker、用户权限这三件事不处理好后面全是泪不建议一上来就跑一键安装脚本。先把运行环境理清楚后面出问题时排查成本会低很多。Ubuntu 22.04 是当下兼容性比较好的选择我用的是ubuntu-22.04.5-desktop-amd64.iso安装的桌面版服务器版同样适用只是少了桌面环境不影响 OpenClaw 本身。2.1 用 nvm 安装 Node.js不要直接用 apt 装OpenClaw 对 Node.js 版本有要求apt 仓库里自带的 Node 版本通常偏旧直接装容易遇到依赖不兼容。推荐用 nvm 安装好处是可以在多个 Node 版本之间随时切换出问题还能快速回滚。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v我实际装的是 Node 20 LTS 版本编译依赖时最稳。这里有个小建议安装完 nvm 后重新打开终端或者手动source ~/.bashrc否则nvm命令会提示找不到。很多人在这一步卡住以为安装失败其实只是当前 shell 还没加载新的环境变量。2.2 Docker 到底用不用得上取决于你要接哪些扩展OpenClaw 本身不一定需要 Docker但如果你接了一些需要隔离环境的技能比如跑 Python 脚本、部署浏览器自动化工具Docker 几乎必然会被用到。就算暂时用不上我也建议提前装好免得后面加功能时手忙脚乱。Ubuntu 上装 Docker 的常规流程sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin装完别忘了把当前用户加进 docker 组不然每条 docker 命令都要 sudosudo usermod -aG docker $USER注意加完用户组后要重新登录一次组权限才会生效。我用的是开发板挂载 Ubuntu 的真实环境磁盘 IO 不高所以 Docker 镜像里跑了轻量服务整体负载还能接受。2.3 统一运行用户和 HOME 目录权限避免一半的权限问题OpenClaw 会把配置、session、日志都写在用户目录下。如果你有时候用 root 启动有时候用普通用户启动配置文件的属主会乱套session 锁问题、权限拒绝问题会接踵而来。我的建议是单独创建一个专用用户比如openclaw所有操作都用这个用户完成。sudo adduser openclaw sudo usermod -aG sudo openclaw sudo usermod -aG docker openclaw su - openclaw这样做的最大好处是隔离。OpenClaw 的配置、日志、session 全部集中在/home/openclaw/.openclaw目录下备份和迁移都很方便也不用担心误操作影响系统其他服务的运行环境。3. 实际安装操作一条脚本路线和一条手动路线我推荐你走第二条OpenClaw 的安装方式主要有两种官方一键脚本和从源码手动安装。如果你只是想在本地快速体验一条脚本足够如果你想长期使用并自己维护手动路线能让你对目录结构、配置文件位置、启动流程完全心里有数。3.1 一键脚本安装但你要知道它到底做了哪些事官方提供了一键安装脚本基本流程是下载安装包、解压到指定目录、自动安装依赖、生成默认配置。在 Ubuntu 上执行大概长这样curl -fsSL https://get.openclaw.ai | bash我的建议很直接脚本可以跑但跑完不要立刻觉得万事大吉。你至少需要知道三件事脚本把主程序装到了哪个目录、默认配置文件在哪、用什么命令启动。不然后面想查日志、换模型、加 channel你会完全不知道怎么下手。我实际遇到的情况是脚本跑完很顺利但启动服务时发现根域名指向不对需要手动改配置文件里的监听地址。这时候不懂目录结构就会被卡住。3.2 从源码安装可控性高得多从源码安装并不复杂关键是版本可控。步骤如下git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm run buildnpm install时如果遇到编译原生模块失败常见原因有两个一是 Node 版本太老二是缺少 python3、make、g 这类编译工具链。Ubuntu 最小化安装经常缺这些提前装好sudo apt install -y python3 make gnpm run build完成后可以通过npm start或项目里提供的启动脚本运行。首次启动会提示初始化配置文件按向导填写模型供应商的 API Key 和默认 Channel 类型即可。在#define命令不生效这类问题上源码安装还有个额外好处你可以直接打开项目里的帮助文件确认当前版本的配置项写法。网络上的很多教程对应的是旧版本字段名已经不一致了照抄很容易白屏。3.3 首次启动和登录看见欢迎提示才算真正跑起来首次启动 OpenClaw 时终端会输出一段初始化信息告诉你配置文件生成在哪个路径、Web 管理界面监听在哪个端口。默认情况下管理界面可能只监听127.0.0.1如果你在远程服务器上部署需要通过 SSH 隧道或者改监听地址为0.0.0.0才能访问。我建议先本地测试再对外开放。首次登录会要求设置管理员口令这个口令和之后 Channel 里 Agent 的对话无关仅用于管理后台。很多人在这一步误以为我已经能用了其实还要继续配置 Channel。4. 接飞书、Teams、ObsidianChannel 配置的实操细节如果 Agent 相当于 OpenClaw 的大脑那 Channel 就是它的五官。只装好 OpenClaw 而不接入任何聊天平台它就只是个待在终端里的命令行工具体现不出真正价值。我实际配置了飞书和 TeamsObsidian 也试过这里把关键步骤和踩坑点写清楚。4.1 Channel 选择的逻辑以及飞书的配置要点在公开对话里让 Agent 回复消息最简单的做法是创建一个机器人应用把 App ID、App Secret 填到 OpenClaw 配置里。飞书这边要用开发者后台创建企业自建应用开启机器人能力然后配置事件订阅地址让飞书把消息事件推送到 OpenClaw 的 Webhook 端口上。配置里要填的核心参数包括App ID 和 App Secret事件订阅的 Encrypt Key 和 Verification TokenWebhook 监听端口默认通常是 8080 或 3000这里有一个非常容易踩的坑飞书对事件订阅地址有签名校验如果 OpenClaw 收到的请求签名不匹配飞书后台会显示事件订阅失败。排查时先看 OpenClaw 日志里有没有收到飞书的挑战请求收到了但验证失败多半是 Encrypt Key 填错如果日志里压根没有请求那要查网络层比如防火墙有没有放行对应端口。另外OpenClaw 在飞书里输出长文本容易被截断这是飞书消息接口本身的限制不是 OpenClaw 的 bug。解决思路是调整 Agent 的回复风格配置让它输出更简短或者在中间加一层消息分段逻辑。我当时在配置里把 max response length 改小截图式长文输出的问题缓解了很多。4.2 接入 Microsoft Teams 的注意点Teams 的接入思路和飞书类似但细节上不同。你需要在 Azure 门户创建一个机器人应用拿到 Microsoft App ID 和密码。然后在 Teams 后台给机器人配置消息端点后端地址要指向 OpenClaw 的 Webhook 端口。我在配置 Teams 时最大的坑是Azure 那边的消息加密选项如果选错了OpenClaw 收到的消息都是乱码。正确做法是确认 OpenClaw 当前版本支持哪种消息加密再在 Azure 上面选对应模式。另外 Teams 的事件推送要求 HTTPS 端点生产环境最好在前面挂一层反代做 TLS 终结开发环境可以临时用 HTTP 和内网穿透工具测试。4.3 模型配置以千问为例把 API Key 和 agent 的对应关系理清模型这块很多人以为配了一个 OpenAI 兼容的 API Key 就万事大吉。OpenClaw 的配置里model provider 和 channel 是独立的但最终对话时Agent 角色会绑定具体模型配置。以千问为例你要确认三样东西Base URL、模型名称、API Key。如果 Base URL 填错即使 Key 是对的请求也会报认证失败很容易误导人以为 Key 有问题。{ model: { provider: openai-compatible, apiKey: sk-你的千问APIKey, baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1, modelName: qwen-plus } }千问的 OpenAI 兼容接口做得比较规范填好上述配置后在 OpenClaw 管理后台里发一条测试消息能收到回复就说明模型链路是通的。我建议先用这种方式做最小验证再接入飞书不然模型没通就接渠道出了问题两个系统都要查。4.4 Obsidian 和本地技能接入的思路Obsidian 的接入更多是利用 OpenClaw 的本地文件读写能力让 Agent 能访问你的笔记库。你需要在配置里告诉 OpenClaw 笔记库的路径并给它授予读写权限。这里要特别注意Ubuntu 下如果笔记库是在图形界面挂载的磁盘路径里可能有空格配置时加上引号否则路径解析会出问题。Obsidian 接入的实用场景很明确让 Agent 帮你整理日记、检索历史笔记、生成周报。关键是给 Agent 设定明确的指令限制它只能访问笔记库目录不要放开成任意路径否则安全性会有隐患。5. 踩坑实录把 Ubuntu 上最典型的几个错误从现象到根因讲清楚这一部分放到最后再讲是因为很多坑都是在前面的安装、配置、接渠道过程中暴露出来的。以下五个问题是我在 Ubuntu 22.04 上实际踩过的每个都附了排查链路建议收藏备用。5.1 agent failed before reply: session file locked (timeout 60000ms)这个报错我在前文已经提过但值得单独拿出来再展开一次。完整排查链路是这样的第一步看 OpenClaw 运行日志确认报错发生在哪个环节。日志里如果出现session file locked直接到 session 目录看文件状态。ls -lah ~/.openclaw/sessions/第二步查看 session 文件的属主和运行进程的用户是否一致。如果不一致chown -R openclaw:openclaw ~/.openclaw第三步杀掉可能残留的旧进程重启 OpenClaw。如果还有锁残留可以手动删除对应的 session 文件。这里要提醒一句删除 session 文件会丢失那段对话的上下文历史所以能保留就尽量保留。5.2 Ubuntu 环境变量配置错误导致 bash 命令全没了这个坑我愿称之为最吓人的坑。当时我想把 OpenClaw 的启动目录写进~/.bashrc的 PATH 里结果手误把 PATH 覆盖成了只有那个目录保存退出后所有常规命令直接无效连ls、sudo都用不了。如果你不幸复现了这个问题不要慌直接全路径调用命令修复/usr/bin/sudo /usr/bin/nano ~/.bashrc进去之后把 PATH 那一行改回标准定义export PATH/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin然后重新加载source ~/.bashrc经历过这次事故之后我一律不在.bashrc里直接写死 PATH而是用独立文件放到/etc/profile.d/下或者先echo $PATH追加原路径绝不覆盖。5.3 Ubuntu 安装 GCC 失败与编译依赖问题装 GCC 失败的场景通常出现在运行sudo apt install -y build-essential时。现象是提示某些软件包版本冲突或者Unable to locate package。第一种情况是因为 apt 源没有更新到最新索引先执行sudo apt update sudo apt upgrade第二种情况是源列表里连universe软件源都没开。检查/etc/apt/sources.list确保里面有universe字段再重试安装。还有个隐藏问题如果你之前折腾过其他编译环境系统里可能残留了多个版本的 gcc导致编译时头文件路径错乱。用gcc --version看一眼版本如果对不上 OpenClaw 的编译要求可以单独指定版本安装sudo apt install -y gcc-12 g-12编译过程中遇到node-gyp报错基本都可以归结为 Python 版本或 make 版本不对把这几个基础工具理顺90% 的问题都会消失。5.4 飞书 / Teams 回调失败与端口监听排查接入飞书或 Teams 后如果消息发出去没回应第一反应不应该是去看 Agent 模型配置而是先确认 OpenClaw 的 Webhook 端口是否真的在监听。ss -tlnp | grep 8080如果端口没监听说明 OpenClaw 的 Channel 没起来如果端口在监听但外网访问不了用curl从外部打一下看通不通curl http://你的服务器IP:8080/healthUbuntu 的 ufw 防火墙如果没放行端口外部请求会被丢掉但本机curl 127.0.0.1是通的这种割裂现象特别有迷惑性。记得检查sudo ufw status sudo ufw allow 8080/tcp5.5 Ubuntu 中文输入法与 OpenClaw 配置的连带问题严格来说中文输入法问题和 OpenClaw 没有直接关系但很多用户是桌面版 Ubuntu经常在配置界面里要输入中文内容结果发现输入法调不出来误以为 OpenClaw 的界面有问题。我用的方案是安装 IBus 框架下的中文输入法sudo apt install -y ibus ibus-pinyin然后到设置-区域与语言-输入源里添加汉语拼音输入源注销重新登录即可。设置完成后配置 OpenClaw 的渠道名称、Skill 描述等中文内容就不会再有障碍。顺带一提如果 OpenClaw 管理后台输入中文丢字优先检查浏览器编码和输入法引擎而不是怀疑程序本身。6. 让 OpenClaw 在 Ubuntu 上常驻运行systemd 托管与日常维护到现在为止OpenClaw 如果是在终端里启动的窗口一关服务就断了。真正要长期用必须把 OpenClaw 注册成 systemd 服务这样才能开机自启、自动重启、统一管理日志。这也是本地一键部署和正式使用之间最重要的一道分水岭。6.1 编写 systemd service 文件把启动流程固下来在/etc/systemd/system/openclaw.service下新建服务文件[Unit] DescriptionOpenClaw Service Afternetwork-online.target docker.service Wantsnetwork-online.target [Service] Useropenclaw Groupopenclaw WorkingDirectory/home/openclaw/openclaw ExecStart/home/openclaw/.nvm/versions/node/v20.17.0/bin/node /home/openclaw/openclaw/dist/main.js Restartalways RestartSec10 EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target这里有几个关键点。User和Group必须是你之前创建的统一运行用户不要用 rootExecStart里的 Node 路径不要写node最好用which node查出的绝对路径避免 systemd 找不到命令Restartalways可以保证进程崩溃后自动拉起来省得半夜服务挂了没人管。写完文件后依次执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclawstatus里看到active (running)并且日志没有报致命错误就说明托管成功了。之后启动、停止、重启服务全部通过 systemctl 操作不再需要手动开终端。6.2 日志查看与常见运维姿势systemd 托管的服务日志统一用 journalctl 查看journalctl -u openclaw -f journalctl -u openclaw --since 1 hour ago-f是实时跟踪排错时候最推荐。如果发现日志刷屏可以调整日志上限避免磁盘被占满sudo journalctl --vacuum-size200M另外要定期检查磁盘空间和内存占用。OpenClaw 跑一段时间后session 文件、日志、缓存都会膨胀写一个简单的定时任务清理crontab -e # 每天凌晨3点清理超过7天的临时文件 0 3 * * * find /home/openclaw/.openclaw/tmp -type f -mtime 7 -delete6.3 版本升级与迁移备份有多少人在这上面栽过升级最常见的错误是直接拉最新代码重启结果配置字段变了服务起不来。我现在的做法是升级前先备份配置和 session 目录再看官方 changelog 里有没有破坏性变更cp -r ~/.openclaw ~/.openclaw.bak-$(date %Y%m%d)备份这个动作每次升级前都做耽误一分钟但能在出问题时省下半天。迁移到新服务器时把整个.openclaw目录打包拷过去保持同样的用户和路径结构基本就能直接跑起来。关于workbuddy这类同类工具的比较我个人的体会是OpenClaw 强在本地控制和多 Channel 接入WorkBuddy 更倾向开箱即用但定制性差一些。如果你想折腾、想要自己的 Agent 掌握在手里OpenClaw 在 Ubuntu 上确实值得投入时间。最后再分享一个小技巧也是我踩过坑换来的安装和配置的全部过程记得把每一步用到的命令和报错截图存成一个 Markdown 文档。OpenClaw 更新速度不慢你三个月后回头看这份记录会比任何网上的教程都管用。Ubuntu 上跑 OpenClaw 这件事本身并不难难的是出问题时愿意顺着日志一步步往根因里钻。钻进去一次后面的路就顺了。
