本地 AI 代理最初往往只是一个“能跑起来”的工具：在桌面机上安装，接入模型，配置几个插件，再接入聊天渠道或浏览器能力。这个阶段的重点是验证可用性，而不是长期运行。
但当一个 AI 代理开始承担更多日常任务，例如消息通道响应、文件处理、浏览器辅助、系统状态检查、项目资料检索，它就不再只是一个临时工具，而会逐渐变成本地基础设施的一部分。此时，运行位置、可用性、状态目录、外部访问入口、权限边界和数据分工都会变得重要。
这次迁移的核心，就是把 OpenClaw 的主安装实例从一台桌面 Linux 主机迁移到一台树莓派上，让树莓派承担长期在线的主服务角色，而桌面机则退回为扩展资源主机。
迁移前的结构
迁移前，OpenClaw 主实例运行在一台日常使用的桌面 Linux 主机上。它同时承担多个角色：
- OpenClaw 主安装实例
- 主工作区
- 状态目录和配置目录
- 消息通道后端
- 浏览器/CDP 能力所在主机
- 大型本地项目所在主机
- 日常桌面使用环境
这种结构在早期很方便。所有东西都在同一台机器上，路径简单，浏览器也直接可见，调试成本低。需要排查时，打开终端就能看到服务、配置和日志。
但随着 OpenClaw 逐渐变成一个长期使用的代理系统，这种结构的问题也越来越明显。
首先，桌面机不是理想的 24 小时在线主机。它可能重启、关机、休眠，也可能因为桌面环境、浏览器、图形会话或用户操作影响服务状态。
其次，桌面机上同时有用户日常使用的程序和 OpenClaw 的自动化任务。一旦 AI 代理具备操作浏览器、文件和系统命令的能力，就必须严格区分“代理可管理的资源”和“用户私人使用的资源”。
第三，桌面机上的 OpenClaw 历史安装路径、配置目录、浏览器 profile、systemd user service、shell alias、旧备份目录等内容逐渐混杂。继续在原地修补，会让整个系统越来越难判断边界。
因此，迁移的目标不是单纯“换一台机器运行”，而是重新划分职责。
迁移后的目标架构
迁移后的结构可以概括为：
树莓派节点：
- OpenClaw 主安装实例
- 主状态目录
- 主工作区
- 消息通道后端
- gateway / dashboard 主入口
- 长期在线运行
桌面节点：
- 不再运行旧 OpenClaw 主实例
- 不再作为 gateway 主机
- 保留浏览器/CDP 扩展能力
- 保留因容量原因暂未迁移的大型项目目录
- 作为按需调用的扩展资源主机
也就是说，树莓派成为 OpenClaw 的主节点，桌面机只保留少量无法或不适合迁移的能力。
这种设计的好处是，主服务变得更加稳定。树莓派功耗低，适合常驻；桌面机可以继续作为高性能或图形资源节点，但不再承担 OpenClaw 主实例的核心状态。
为什么选择树莓派作为主节点
树莓派并不适合承载所有任务。它的存储容量、CPU 性能和 I/O 能力都有限，尤其不适合大型数据库、大型本地项目和图形浏览器长期高负载运行。
但它很适合承担以下角色：
- 低功耗常驻主机
- 消息通道后端
- OpenClaw gateway
- 轻量级工作区
- 配置、规则和记忆文件的主存放位置
- 外部请求的统一入口
对一个本地 AI 代理来说，真正需要 24 小时在线的部分，往往不是所有计算任务，而是“入口”和“状态”。只要主实例、消息入口和规则文件稳定在线，重型任务可以交给其他机器按需完成。
这也是本次迁移的基本思路：主实例轻量化，扩展能力外置化。
域名和外部入口保持不变
迁移过程中，一个重要原则是尽量不改变外部访问入口。
原来的外部访问结构大致是：
公网域名
-> 反向代理
-> 内网主机上的 OpenClaw gateway
迁移后，公网域名和反向代理入口保持不变，只是后端实际承载 OpenClaw gateway 的机器从桌面机变成了树莓派。
这样做的好处是：
- 外部 webhook 地址不需要大规模重配
- 已有消息通道配置可以继续使用
- dashboard 访问入口保持一致
- 迁移风险集中在内网后端，不扩散到公网配置
也就是说，公网入口不代表 OpenClaw 必须运行在原来的机器上。只要反向代理或内网转发链路指向新的后端，外部域名可以保持稳定。
主状态目录和工作区迁移
OpenClaw 迁移中最关键的不是程序本身，而是状态和工作区。
程序可以重新安装，但以下内容必须谨慎迁移：
- 配置文件
- SecretRef 或 token 引用
- 插件配置
- 工作区文件
- memory 文件
- sessions / transcript
- channel 配置
- dashboard 授权状态
- 插件 registry 状态
迁移后，树莓派上的主目录成为新的事实来源：
主状态目录：<saturn-openclaw-state>
主工作区：<saturn-openclaw-workspace>
桌面机上的旧状态目录不再作为 OpenClaw 主状态来源。旧安装路径、旧服务、旧命令入口、旧 shell alias 也需要清理，否则后续很容易误操作旧实例。
这一步的核心判断是：迁移完成后，只能有一个主实例。否则一旦桌面机和树莓派上都残留可启动的 OpenClaw gateway，就很难判断当前响应消息的是哪个实例，配置修改写到了哪边，插件状态又属于哪一边。
桌面机不再是主实例，但仍然有价值
迁移完成后，桌面机没有被完全废弃，而是被重新定位。
它保留两个主要角色：
第一，作为浏览器/CDP 扩展主机。
树莓派可以运行 OpenClaw 主实例，但不一定适合运行完整图形浏览器。桌面机本来就有图形环境、浏览器、窗口系统和更强的桌面交互能力，因此更适合提供按需浏览器能力。
第二，作为大型项目的扩展存储和计算节点。
部分大型项目由于容量或性能原因，没有迁移到树莓派。这类目录继续保留在桌面机上，由 OpenClaw 在需要时通过 SSH 或其他方式调用。
因此，迁移后的桌面机并不是“旧主机残留”，而是一个明确降级后的扩展资源节点。
为什么不能把所有东西都迁到树莓派
理论上，完整迁移意味着所有工作区、项目、浏览器 profile 和历史数据都转移到树莓派。但实际操作中，这并不总是合理。
树莓派的 SD 卡容量有限，大型项目、虚拟环境、数据集、历史输出文件可能会占用大量空间。强行全部迁移，会让树莓派成为新的瓶颈。
更合理的做法是区分三类数据：
必须迁移：
- OpenClaw 主配置
- 主工作区
- 规则文件
- 记忆文件
- 消息通道配置
- 当前运行状态所需文件
可以留在桌面机：
- 大型项目
- 数据集
- 图形浏览器 profile
- 临时输出
- 不适合放在 SD 卡上的资源
应该清理：
- 旧安装目录
- 旧服务文件
- 已经迁移且内容完全一致的重复文件
- 旧 shell alias / PATH 残留
- 无意义的历史缓存
这样，迁移不是简单复制，而是一次结构整理。
迁移后的最终分工
迁移完成后，系统分工变得清晰：
树莓派节点：
- OpenClaw 主实例
- gateway
- dashboard
- 消息通道
- 主工作区
- 长期规则和记忆
- 插件配置
桌面节点：
- 不运行旧 OpenClaw gateway
- 不保存主状态
- 保留专用浏览器 profile
- 保留大型扩展项目
- 按需接受主节点调用
这种分工避免了“两个主实例”并存，也避免了桌面机长期承担后台服务的压力。
迁移的真正目的
这次迁移表面上是从一台桌面机迁到一台树莓派，实际上是一次本地 AI 代理基础设施的角色重构。
迁移前，OpenClaw 是一个运行在桌面机上的工具。
迁移后，它变成了一个以树莓派为主节点、桌面机为扩展节点的本地代理系统。
最重要的变化不是路径，也不是端口，而是职责边界：
- 主实例只有一个
- 状态来源只有一个
- 桌面机不再承载主服务
- 扩展资源按需调用
- 浏览器和大型项目从主实例中解耦
- 旧实例彻底退出运行链路
这让整个系统更接近一个可长期维护的结构，而不是不断叠加补丁的临时安装。
小结
本次迁移可以总结为一句话：
把 OpenClaw 的主状态和长期在线能力迁到树莓派，把桌面机降级为按需调用的扩展资源主机。
这种结构并不追求所有任务都在树莓派上完成，而是让树莓派承担稳定入口和主状态，让桌面机继续提供浏览器、图形环境和大型项目能力。
对本地 AI 代理来说，这种分工比“所有东西塞进一台机器”更容易维护，也更容易控制风险。
后续还需要处理迁移后的插件修复、旧实例清理、浏览器/CDP 调用规则、AI 代理误操作边界，以及重复文件审计清理等问题。这些内容属于迁移后的收尾和加固阶段，可以拆成后续几篇继续展开。