OpenClaw 换机迁移这种事看起来就是“把旧机器上的服务搬到新机器”实际上前后我踩了三次坑才总结出这套能直接照抄的流程。第一次只在旧机器上拷了配置目录结果新机器起来后会话历史全丢第二次备份时服务还在运行恢复后频繁报session file locked (timeout 60000ms)第三次想省事把整个系统盘打包过去路径和权限全乱Teams 机器人和 Obsidian 插件集体罢工。所以如果你正在准备 OpenClaw 换机迁移别急着装环境先把这篇文章从头看一遍很多坑我替你踩完了。1. 换机迁移前先想清楚这三件事1.1 你以为在迁文件其实在迁一套运行状态OpenClaw 这类开源助理框架和普通 Web 服务最大的区别在于它不仅有配置和代码还有大量“运行状态”。常见的数据包括会话记录、长期记忆、人物设定、插件配置、媒体附件、密钥凭据甚至还有一些自动任务的执行状态。很多人换机时只记得复制安装目录和.env结果新机器虽然能启动但它已经不记得你是谁了。我习惯用一个类比来解释换机迁移不是“买一台新电脑重新装软件”而是“帮你整个书房搬过去”。程序本体只是书架真正值钱的是书架上那些旧笔记、日程表和联系人——对应到 OpenClaw就是sessions目录、记忆数据库、附件目录和.env密钥文件。只搬书架不搬书等于白搬。另外提一句经常有人纠结 OpenClaw 和 WorkBuddy 哪个好。我的态度很明确换机迁移阶段尽量不要趁机动平台或换版本。迁移本身就是高风险操作再把“换工具”“换版本”塞进来出了问题你根本分不清是数据没迁对还是新平台配置不对。想对比工具等环境稳定了再单独拉一套实例对比别拿生产数据做实验。1.2 新旧环境差异清单动手之前先列一份新旧机器的环境差异清单。OpenClaw 的依赖环境、数据格式、系统服务方式都会影响迁移成功率。下面是我每次换机前都会核对的项目检查项旧机器新机器影响说明操作系统版本Ubuntu 22.04Ubuntu 24.04系统库、glibc、Python 版本不同可能导致依赖编译失败CPU 架构amd64arm64Docker 镜像和 Python 包需要不同平台版本Python 版本3.103.11/3.12部分第三方库在 3.12 下要重装或换版本Node 版本1820前端插件、自定义脚本可能有兼容问题Docker/compose24 v226 v2Compose 文件语法差异数据目录位置/home/olduser/.openclaw/var/lib/openclaw配置里的绝对路径需要全局替换公网入口云服务器弹性 IP新的弹性 IPTeams Webhook、GitHub Webhook 要同步更新时区/语言Asia/Shanghai, zh_CNAsia/Shanghai, zh_CN定时任务和日志时间错乱很难排查差异清单不用太复杂关键是发现哪些东西不能“原样复制”。比如旧机器是 amd64 架构新买的是 arm64 开发板那么直接拷贝~/.venv是跑不起来的必须重新创建虚拟环境并安装依赖。这一步别偷懒。1.3 四步迁移法备份、搬运、恢复、验证我给自己定了一个四步迁移法备份、搬运、恢复、验证。每一步都产出明确结果不做完不进入下一步。备份停掉 OpenClaw 服务把所有数据目录打包生成校验文件。搬运用scp、rsync或云盘同步到新机器搬运后先做 hash 校验。恢复在新机器上部署同版本 OpenClaw恢复配置和环境变量安装依赖。验证按消息入口、会话记忆、插件能力、定时任务四个维度做逐项测试。这个流程看起来简单但很多人直接在“搬运”这一步翻车。比如用网盘传压缩包传输中断了也不知道或者用cp -r直接复制运行中的目录导致锁文件和半写入文件一起被复制。所以每完成一步都留出时间做完整性对比别急着启动服务。2. 备份阶段把会话、记忆、密钥一个不落打包2.1 不同部署方式的数据目录地图OpenClaw 的部署方式不同数据目录差别很大。我见过的一键脚本安装、源码安装、Docker 部署三种方式默认路径都不一样一键脚本安装数据通常放在当前用户家目录下的.openclaw/里面会有sessions、memory、media、config等子目录。源码安装项目目录下一般有data/或.openclaw/同时.env文件就在项目根目录或~/.config/openclaw/。Docker 部署数据通常在命名卷里比如openclaw_data、openclaw_config需要通过docker volume ls才能确认。最保险的做法是先用find把所有相关目录定位出来sudo find / -maxdepth 4 -type d -name *openclaw* 2/dev/null如果是 Docker 部署还要重点确认/var/lib/docker/volumes/下有哪些卷是 OpenClaw 在用的。一个很常见的坑是只迁移了代码目录忘了迁 Docker 卷结果容器启动后配置还在历史会话全没了。2.2 session 文件和“session file locked”是怎么来的备份 OpenClaw 时最容易忽略的就是sessions目录。每个会话对应一个 session 文件里面保存了当前对话上下文、工具调用状态、消息断点等。OpenClaw 在读写会话时会对文件加锁避免多个进程同时修改同一个会话。session file locked (timeout 60000ms)这个报错的本质就是某个会话文件被锁住了而等待锁超时时间到了 60 秒还拿不到。常见原因有三个换机前没有停服务直接把正在写入的 session 文件复制走了。旧进程异常退出锁文件残留没清理。新旧机器同时想操作同一个会话文件比如迁移后旧机器服务没关新机器也启动了。所以在备份前我不建议只执行cp -r更不建议在服务运行时打包。先停服务再确认进程退出最后再打包这样 session 文件才是完整一致的。后面第 6 节我会专门讲怎么处理已经出现的锁文件报错。2.3 密钥、环境变量和插件的登记表备份不只是打包文件还要做一份“密钥登记表”。OpenClaw 的正常运行通常依赖一堆外部服务大模型平台的 API Key、机器人平台的应用密钥、数据库密码、Webhook 签名密钥等。这些凭据一般都在.env文件或环境变量里。迁移前我会执行这些命令把环境变量和密钥位置摸清楚# 查看当前 OpenClaw 相关环境变量 env | grep -i openclaw env | grep -iE api_key|token|secret # 在配置目录里查找硬编码密钥排除日志 grep -rE sk-[A-Za-z0-9]|token|secret|password \ ~/.openclaw --exclude*.log --exclude*.session -l注意找到的密钥不要直接截图发到聊天工具也不要写在记事本里。我会把密钥先导入密码管理器再在密码管理器的备注栏里记清楚“哪个密钥对应哪个服务”。迁移完成后逐项填回新机器的.env。宁可慢一点也不要漏掉一个。2.4 用 tar 做一个可靠备份包打包备份我强烈推荐tar不要用cp -r直接复制目录。因为tar能保留文件权限、ACL、扩展属性还不容易因为符号链接问题导致目录结构混乱。下面是我实际使用的备份命令# 1. 停掉 OpenClaw 服务 sudo systemctl stop openclaw # 2. 如果是 Docker 部署先停容器 cd /opt/openclaw docker compose down # 3. 打包数据目录以数据在 /home/openclaw/.openclaw 为例 cd / sudo tar --xattrs --acls --exclude*.log \ -czf /backup/openclaw_backup_$(date %F).tar.gz \ home/openclaw/.openclaw etc/openclaw var/lib/openclaw 2/dev/null # 4. 生成校验文件 cd /backup sha256sum openclaw_backup_$(date %F).tar.gz openclaw_backup_$(date %F).sha256这里有两个细节容易忽略。第一tar解压时如果路径用了绝对路径会有 warning所以我喜欢先cd /再用相对路径打包恢复时cd /后再解压。第二日志文件通常很大且迁移价值低用--exclude*.log排除能明显缩小备份体量。如果会话数据特别大可以再加--excludesessions/*.tmp把临时文件排除掉。3. 在新机器上重新部署 OpenClaw3.1 部署方式怎么选源码、Docker 还是一键脚本新机器上重新部署 OpenClaw我建议尽量复刻旧机器的部署方式。不要旧机器用 Docker新机器换成一键脚本因为数据目录、进程管理方式、日志位置全都不一样迁移工作量会翻倍。源码部署适合要改代码、调试插件的场景。灵活但升级维护要自己管理。Docker 部署环境隔离好迁移卷方便适合服务器长期运行。缺点是要额外维护镜像和 compose 文件。一键脚本部署最快适合新机器初期搭建也适合不熟悉 Linux 的用户。但脚本默认路径和配置项不一定满足你后续的自定义需求。无论选哪种一个底线是不要用root用户跑 OpenClaw。我见过直接把服务装在 root 家目录下的一旦会话文件权限错乱整个数据目录都可能没法读。创建一个独立的openclaw用户是最省心的做法。3.2 Ubuntu 新环境基础配置以 Ubuntu 22.04/24.04 为例新机器装完系统后先做一轮基础初始化sudo apt update sudo apt upgrade -y sudo apt install -y git curl build-essential \ python3 python3-venv python3-pip nodejs npm ca-certificates如果要用 Docker 部署再装 Dockercurl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker sudo usermod -aG docker openclaw如果你用的是国内云服务器发现 Docker 拉镜像特别慢记得去云厂商的控制台找容器镜像加速器配置把它写到/etc/docker/daemon.json里然后重启 Docker。这一步能省很多时间但注意不要使用任何来路不明的镜像地址。然后创建专用用户和数据目录sudo useradd -r -s /bin/bash openclaw sudo mkdir -p /opt/openclaw /var/lib/openclaw /etc/openclaw sudo chown -R openclaw:openclaw /opt/openclaw /var/lib/openclaw /etc/openclaw3.3 恢复配置、数据和依赖新机器装好基础环境后开始恢复备份。解压前先把校验文件导进来cd /backup sha256sum -c openclaw_backup_$(date %F).sha256校验通过后解压cd / sudo tar --xattrs --acls -xzf /backup/openclaw_backup_$(date %F).tar.gz如果旧机器的数据目录路径和新机器不一样比如旧机器是/home/olduser/.openclaw新机器是/var/lib/openclaw那就要做路径替换。我通常会在配置文件目录里全局搜一遍旧路径sudo grep -R /home/olduser /etc/openclaw /var/lib/openclaw /opt/openclaw 2/dev/null确认需要替换的配置文件后再用sed批量替换sudo sed -i s|/home/olduser/.openclaw|/var/lib/openclaw|g \ /etc/openclaw/openclaw.env \ /etc/openclaw/config.yaml路径替换完还要重新设置文件权限否则服务会报权限错误sudo chown -R openclaw:openclaw /var/lib/openclaw /etc/openclaw /opt/openclaw sudo chmod 600 /etc/openclaw/openclaw.env如果是源码部署需要重新创建虚拟环境并安装依赖cd /opt/openclaw python3 -m venv .venv .venv/bin/pip install -r requirements.txt如果是 Docker 部署先恢复卷数据再重新docker compose up -d。不要图省事直接把旧机器的.venv整个拷贝过来Python 虚拟环境对系统路径敏感跨机器迁移后大概率起不来。4. 接入层迁移Teams、Obsidian 和外部服务4.1 Microsoft Teams 机器人接入点要重新验证很多用户把 OpenClaw 接进 Microsoft Teams让它变成团队里的助理机器人。换机后最容易被忽略的就是 Teams 后台的 Messaging Endpoint。你的新机器公网 IP 或域名变了旧机器上配置的 Webhook 地址就失效了。具体操作时我一般按这个顺序来确认新机器上 OpenClaw 的对外地址比如https://assistant.example.com/api/messages。登录 Azure 门户或 Teams 机器人管理后台找到对应的 Bot Framework 应用。更新 Messaging Endpoint 为新的完整地址。确认MicrosoftAppId和MicrosoftAppPassword已经写入新机器.env。在 Teams 里给机器人发一条消息确认能正常收到并回复。这里有一个小坑如果新机器没有公网域名只是临时测试很多人会用内网映射工具暴露服务。换机后映射工具的地址也会变需要同步更新到 Teams 后台。我建议生产环境尽量用固定域名 反向代理地址变化时只改 DNS不用去后台改一堆配置。4.2 Obsidian 插件与知识库路径迁移OpenClaw 集成 Obsidian 后一般会读写你的笔记库让助理可以从笔记里检索上下文。换机时不只是把笔记目录复制过去还要注意插件配置里的绝对路径。我的经验是先迁移整个 Vault 目录再处理 OpenClaw 侧的插件配置用rsync把 Obsidian Vault 同步到新机器比如放到/data/obsidian-vault。在 OpenClaw 插件配置里找到与 Obsidian 相关路径把旧路径替换成新路径。检查 Vault 里的.obsidian/plugins目录是否完整尤其是第三方插件有没有因为新机器缺少依赖而失效。如果 Vault 在旧机器上开启了同步盘比如坚果云或其他云同步迁移后要注意文件冲突和延迟最好先关闭同步等本地 Vault 完全一致后再恢复。我还习惯在迁移后做一次“读写测试”让 OpenClaw 读取一篇指定笔记并总结再新建一篇测试笔记确认它有权限写回 Vault。只有读不够写不了的话后续很多自动化流程都会卡住。4.3 其他外部服务和定时任务除了 Teams 和 ObsidianOpenClaw 还可能接了定时邮件、Webhook、数据库、语音服务等。这些接入项迁移时最容易漏掉。定时任务用crontab -l导出旧机器任务再在新机器上crontab -e恢复。如果 OpenClaw 用自己的任务调度配置则直接迁配置目录即可。Webhook 回调如果外部平台定期回调 OpenClaw比如支付回调、GitHub Webhook记得在新机器换好地址后去平台后台更新 Callback URL。IP 白名单有些 API 平台会限制调用来源 IP。新机器公网 IP 变了API 可能报 403。遇到这种情况先查平台后台的 IP 白名单把它更新掉。本地数据库如果 OpenClaw 用了 SQLite/MySQLSQLite 建议停服后直接拷贝数据库文件MySQL 则先用mysqldump导出再导入新库。不要直接把运行中的数据库目录拷走。4.4 在云服务器上迁移需要注意什么如果新机器是阿里云这种云服务器还有一个容易忽略的问题安全组和防火墙。常见场景是 OpenClaw 服务起来了但 Teams 或 Webhook 访问不了一查发现是安全组没放行对应端口。我的建议是只放行业务需要的端口不要图方便把0.0.0.0/0全部放通。用ufw或云安全组同时配置双保险。新机器配置公网 IP 后先在本地curl验证服务再通过公网地址验证区分问题是服务问题还是网络问题。如果用的云服务器是免费试用实例内存和磁盘通常不大。数据目录建议挂载到独立云盘或对象存储避免后续系统盘扩容/重置导致数据丢失。云服务器迁移还有一个好处可以先用旧机器数据快照做新机器的数据盘然后用临时实例验证数据完整性确认没问题后再切换生产。这套“先快照后验证再切换”的流程能极大降低迁移风险。5. 启动服务与完整验证5.1 用 systemd 托管避免手动 nohup新机器上启动 OpenClaw我强烈建议不要手动nohup python3 -m openclaw 而是写一个 systemd 服务。这样开机自启、崩溃重启、日志管理都方便。以下是一个参考配置[Unit] DescriptionOpenClaw Service Afternetwork-online.target Wantsnetwork-online.target [Service] Useropenclaw Groupopenclaw EnvironmentFile/etc/openclaw/openclaw.env WorkingDirectory/opt/openclaw ExecStart/opt/openclaw/.venv/bin/python -m openclaw Restarton-failure RestartSec10 NoNewPrivilegestrue [Install] WantedBymulti-user.target如果你是 Docker 部署ExecStart 改成ExecStart/usr/bin/docker compose upExecStop 改成ExecStop/usr/bin/docker compose down同时 User 改成有 docker 权限的用户。写完配置后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw systemctl status openclaw这里要注意EnvironmentFile对应的.env文件权限要设成 600避免其他用户读到密钥。5.2 服务起来后按这个清单逐项验证服务能启动不代表迁移成功。我每次换机后都会跑一遍验证清单逐项打勾进程状态systemctl status openclaw是 running不是不断地 restart。日志输出journalctl -u openclaw -f确认没有 ERROR、Traceback。新会话用普通用户发一条消息确认可以正常回复。旧会话从 Web UI 或客户端打开历史会话列表确认旧会话还在历史上下文还能带上。记忆数据问一个旧会话里聊过的话题看它能不能引用之前的记忆内容。附件文件检查媒体目录里的旧图片/文件是否都存在路径是否还能访问。Teams 接入在 Teams 里给机器人发消息并验证回包速度。Obsidian 插件让助理读取指定笔记再新建一条临时笔记并删除。定时任务手动触发一次定时任务确认执行日志正常。验证清单最好打印出来一项项过。我在第二次迁移时就是因为跳过了“附件文件”验证等到用户反馈图片打不开才发现媒体目录没同步非常被动。5.3 日志检查与数据回滚预案迁移后 24 小时内日志是最重要的观察窗口。我习惯在换机后的第一天多刷几次日志尤其是这几个关键词error、locked、timeout、permission denied、connection refused。同时备份包先不要删至少保留两周。如果新机器连续出现无法解决的问题果断回滚旧机器。回滚预案在迁移前就要想好旧机器服务是否还能正常启动旧机器数据有没有被清理如果旧机器已经格式化能不能从云盘快照恢复我见过最惨的情况是换机后新环境一直报错旧机器又已经重置系统备份包还在旧机器数据盘里一起没了。所以备份包一定要存在“第三处”可以是云存储也可以是另一台机器。多一份备份迁移就多一条退路。6. 常见问题速查迁移后最容易踩的五个坑6.1session file locked (timeout 60000ms)该怎么处理这个报错在换机后非常常见。如果你迁移前是从运行中的服务直接复制数据新机器启动时大概率会遇到。处理步骤我亲测有效# 1. 确认进程状态 systemctl status openclaw ps aux | grep openclaw # 2. 看看哪些进程持有会话文件 lsof /var/lib/openclaw/sessions/*.session # 3. 停掉服务 systemctl stop openclaw # 4. 删除残留的锁文件 find /var/lib/openclaw -name *.lock -delete # 5. 确认没有持有会话文件的进程后再启动服务 systemctl start openclaw如果删掉锁文件后重启仍然报这个错多半不是锁残留而是多个 worker 并发处理同一个会话导致的。这时候去查一下 OpenClaw 是否配置了多个 worker 或 async 并发改成单 worker 处理会话或者增大锁超时时间才能从根本上解决。6.2 机器人“失忆”了旧会话和记忆全部为空迁移后如果机器人不认识你第一反应不是重新训练而是检查数据目录有没有正确恢复。常见原因有三个一是备份时只拷了配置目录没拷会话和记忆目录二是路径替换没做全服务还在读默认的空数据目录三是 Docker 部署时卷没挂载或挂载到错误位置。另外如果你用的是 SQLite 记忆库迁移时直接复制.db文件是可行的但前提是服务必须处于停止状态。如果从运行中的数据库复制SQLite 的 WAL 和 SHM 文件可能没一起写入主库导致部分记忆丢失。停服后再复制数据库文件或者用 SQLite 的.backup命令导出会更稳妥。6.3 密钥明明复制了却一直报认证失败这种情况通常是.env加载问题。检查三点新机器的.env文件是不是真的被 systemd 的EnvironmentFile加载到了。文件里有没有多余空格、引号、换行符尤其是从聊天工具复制的时候。.env文件权限是否太开放chmod 600之后再重启服务。还有一种可能是外部平台校验了 IP 白名单。换机后新公网 IP 不在白名单里API Key 本身有效但请求被平台拒绝。去对应平台后台把新 IP 加进去一般就能解决。6.4 插件加载失败Obsidian 插件连不上插件加载失败最常见的两种原因依赖没装全和路径没更新。源码部署时如果你换了 Python 版本某些插件依赖需要重新编译或升级Docker 部署时插件目录可能没有挂载进容器或者挂载路径和配置不一致。Obsidian 插件连不上多半是 Vault 路径不对或者 Vault 目录权限不足。用ls -ld /data/obsidian-vault查看目录权限确认 OpenClaw 运行用户对它有读写权限。如果还没有解决问题把 OpenClaw 日志里关于 Obsidian 插件的报错信息完整搜一遍通常日志里会直接给出路径访问失败的具体原因。6.5 端口被占用或防火墙挡了 Webhook换机后外网服务访问不了先做“从外到内”的排查先确认新机器安全组是否放行对应端口再确认系统防火墙ufw status最后确认服务进程是否真的监听在0.0.0.0而不是只有127.0.0.1。如果 Webhook 地址变化了还要去外部平台更新回调 URL。很多平台的回调地址有 TLS 校验如果新机器域名证书没配置好回调请求会在握手阶段失败。用curl -I https://你的域名/api/messages自己测一下能避免很多无效沟通。最后再说一个我后来养成的习惯每次换机前我会先在新机器上启动一个临时实例用同样的备份数据跑一遍“会话恢复—插件调用—外部消息接入”全链路验证通过后再切换正式流量。这个过程熟练之后只需要几十分钟。别嫌麻烦比起生产数据丢了再补救这点时间非常值。