主实例迁移完成，并不意味着 OpenClaw 已经完全恢复到可用状态。
对一个本地 AI 代理系统来说，真正复杂的部分往往不在安装程序本身，而在迁移之后的状态修复：旧路径残留、插件注册状态、SecretRef 引用、消息通道、Dashboard 授权、历史会话索引等，都可能因为主机和路径变化而出现问题。
本篇记录的是 OpenClaw 主实例迁移到新的常驻节点后，如何逐步修复运行状态，并最终确认系统恢复正常。
迁移后最先暴露的问题：路径仍指向旧主机
迁移后，OpenClaw 的主状态目录和工作区已经转移到新主机，但部分内部记录仍然指向旧主机上的路径。
典型表现是：消息通道能够收到请求，但代理长时间卡在处理中，或者表现为“正在输入”，最终没有正常回复。
这类问题的根因通常不是模型不可用，也不是消息平台本身故障，而是 OpenClaw 内部仍然认为工作区位于旧路径。例如：
旧工作区路径：<old-host-workspace>
新工作区路径：<new-host-workspace>
当 attestation、session snapshot、workspace state 等记录仍然引用旧路径时，OpenClaw 在处理任务时可能会尝试访问一个已经不存在的 workspace，从而导致任务无法继续。
因此，迁移后的第一步不是急着修插件，而是确认：
当前 OpenClaw 主实例实际使用哪个 workspace
配置中是否还残留旧 workspace 路径
session / attestation / snapshot 是否仍引用旧路径
消息通道是否能真正完成一次回复
路径修复完成后，消息通道才恢复正常响应。
插件状态异常：目录存在，但 registry 不认识
迁移后另一个明显问题是插件 warning。
从文件系统看，相关插件目录可能已经随状态目录迁移过来，目录本身存在，权限也正常。但 OpenClaw 启动或进入 TUI 时仍然提示：
plugin not installed
这说明问题不一定是插件文件缺失，而可能是插件 registry、host peer link 或 managed npm plugin 状态没有正确恢复。
这类问题比较容易误判。因为目录存在会让人以为插件已经安装完成，但 OpenClaw 运行时真正依赖的是它自己的插件注册和加载状态，而不仅仅是文件是否存在。
处理方式是使用 OpenClaw 自身的修复工具重新校正插件状态，例如：
openclaw doctor --fix
修复后需要再次确认：
openclaw config validate
openclaw plugins inspect <plugin-name> --runtime --json
理想状态下，插件应该显示为：
enabled: true
status: loaded
这说明插件不仅在磁盘上存在，而且已经被 OpenClaw runtime 正确识别和加载。
插件 allowlist：过窄会导致功能缺失
插件修复之后，还可能遇到另一个问题：插件 allowlist 过窄。
如果 allowlist 只包含少数几个迁移时手动修复过的插件，OpenClaw 启动时虽然不会再报错，但实际加载的插件数量会减少，部分原有能力会消失。
因此，迁移后需要对照原实例的功能，恢复完整 allowlist。
这一类配置不是越少越好。allowlist 的作用是明确允许哪些插件加载，但如果它只包含少数几个插件，就等于把其他原本可用的插件禁掉了。
一个较合理的迁移后检查流程是：
1. 先让配置通过 validate
2. 查看启动日志中实际 loaded plugins 数量
3. 对照迁移前功能集合
4. 恢复需要长期使用的插件 allowlist
5. 再次重启并确认 loaded plugins 数量符合预期
这一步的目标不是“没有 warning”这么简单，而是恢复迁移前应有的功能范围。
gateway auth：从环境变量 SecretRef 改成文件 SecretRef
Dashboard 和 gateway 认证是迁移后必须确认的部分。
迁移过程中，gateway password 或 token 可能临时使用环境变量 SecretRef，例如：
gateway.auth.password -> env provider
这种方式在临时测试时可以工作，但长期运行时并不理想。因为它依赖当前 shell、systemd environment 或 EnvironmentFile，一旦进入 TUI、Dashboard、不同 shell 或不同启动方式，就可能出现认证信息取不到的情况。
更稳定的方式是使用 file SecretRef，把 gateway password 存放在 OpenClaw 状态目录下的 secrets 文件中，再让配置引用这个文件 provider。
抽象结构如下：
<openclaw-state>/secrets.json
-> gateway password
OpenClaw config
-> gateway.auth.password
-> file SecretRef
这样做的好处是：
- 不依赖当前 shell 环境变量
- 不依赖手动 source env 文件
- TUI 和 gateway 都能通过同一套 SecretRef 读取认证信息
- 长期运行更稳定
迁移后，只要 openclaw tui 能正常进入，不再因为 SecretRef 或 auth 配置报错，就说明这一层基本恢复正常。
Dashboard：headless 主机不需要本机浏览器
迁移到树莓派或服务器类主机后，一个常见误区是认为 Dashboard 必须在新主机本机打开浏览器。
实际上并不需要。
在无桌面环境的主机上，可以使用：
openclaw dashboard --no-open
或者：
openclaw dashboard
如果主机没有浏览器，OpenClaw 会在终端里打印 Dashboard URL。需要注意的是，如果输出地址是：
http://127.0.0.1:<port>/
这个 127.0.0.1 指的是 OpenClaw 主机本身，而不是远程桌面机或访问者当前使用的电脑。
因此，实际访问时应根据部署方式选择：
- 通过 SSH tunnel 访问本机端口
- 通过已有反向代理域名访问
- 或使用内网地址访问
如果原本已经有稳定的反向代理入口，迁移后只要后端指向新主机，Dashboard 仍然可以通过同一个外部入口访问。
Dashboard 密码不会自动打印
Dashboard 命令通常只打印访问 URL，不会把 gateway password 或 token 明文拼在 URL 中。
这是一种合理设计。认证信息应该由用户或管理员从配置的 SecretRef 来源中查看，而不是被 CLI 随意输出。
因此，如果 Dashboard 页面要求输入密码，应检查当前 OpenClaw 的 auth 配置：
openclaw config get gateway.auth.password
openclaw config get gateway.auth.token
openclaw config get secrets.providers
如果 gateway password 使用 file SecretRef，则需要到对应 secrets 文件中查看实际值。这个值只应在本机终端查看，不应复制到公开聊天、日志或博客中。
公开记录中只需要写明：
Dashboard 使用 gateway password 认证
密码由 SecretRef 管理
实际值存放在本机 secrets 文件中
不应公开任何真实 token、password 或 secret path 的敏感内容。
已授权设备：为什么没有再次要求 pairing
Dashboard 登录后，有时不会再次触发设备授权。这通常不是异常，而是因为之前的浏览器或设备已经配对过。
可以通过设备列表命令查看当前状态：
openclaw devices list
输出中如果显示：
Paired
就说明已经存在授权设备。此时 Dashboard 只需要通过 gateway password，未必会再次要求 pairing。
更详细的检查可以使用 JSON 输出：
openclaw devices list --json
迁移后应该确认两件事：
1. 是否存在已授权设备
2. 是否存在不明 pending pairing request
如果没有 pending request，且已有 paired device 能正常访问 Dashboard，就不需要重新授权。
历史会话和 transcript：不要轻易 cleanup
迁移后，OpenClaw 的 session 和 transcript 也需要检查。
在修复过程中，工具可能会提示存在 orphan transcript 或 stale path。这类提示不能直接理解为“历史会话无用，可以删除”。
原因是，迁移会改变路径。某些 session snapshot 或 transcript 索引可能还指向旧路径，导致修复工具认为它们是孤立文件。但这些文件本身可能仍然是有效历史记录。
比较稳妥的处理方式是：
1. 不急着 archive 或 delete orphan transcript
2. 先修复 stale path
3. 检查 sessions list 是否能正常列出
4. 做 cleanup dry-run
5. 确认不会删除有效 transcript 后再考虑清理
例如，可以先执行类似 dry-run 的检查，而不是直接清理：
openclaw sessions cleanup --dry-run
如果 dry-run 显示不会 prune missing transcripts、不会 remove entries，说明索引修复后历史会话基本恢复正常。
这一步的原则是：迁移后的历史记录优先保留，除非已经确认某些文件确实无用。
消息通道验收：必须做一次真实回复
配置 validate 通过、插件 loaded、Dashboard 能打开，并不代表迁移已经完全成功。
最终仍然需要通过消息通道做真实验收，例如：
- Telegram 能否收到消息
- LINE 能否触发回复
- Nextcloud Talk webhook 是否仍然有效
- 模型调用是否正常
- workspace 路径是否正确
- 代理是否能完成一次完整任务
尤其是迁移后曾出现过“收到消息但不回复”的情况，因此真实消息回环测试是必要的。
一次完整验收应包括：
1. 消息平台发起请求
2. OpenClaw gateway 收到请求
3. 插件正常处理
4. 模型正常响应
5. 回复成功发回消息平台
6. 日志中没有旧路径错误
只有这条链路跑通，才能认为迁移后的主实例恢复可用。
迁移后修复的优先顺序
迁移后问题很多，如果没有顺序，很容易陷入反复修补。
比较合理的顺序是：
1. 确认主实例路径
2. 修复 workspace / attestation / stale path
3. 确认 gateway 服务运行
4. 修复 SecretRef 和 auth
5. 修复插件 registry
6. 恢复插件 allowlist
7. 检查 Dashboard 登录
8. 检查 paired devices
9. 检查 sessions / transcript
10. 做消息通道真实验收
这个顺序的好处是从底层状态开始，逐步到外部功能。否则很可能出现 Dashboard 能打开但消息通道不能回复，或者插件加载了但 workspace 路径仍然错误的情况。
小结
OpenClaw 主实例迁移后，真正需要修复的是运行状态，而不仅仅是程序安装。
本次迁移后的关键修复点包括：
- 修复旧 workspace 路径残留
- 修复插件 registry 和 managed plugin 状态
- 恢复合理的 plugin allowlist
- 将 gateway auth 调整为更稳定的 file SecretRef
- 明确 Dashboard 在 headless 主机上的访问方式
- 找回 gateway password 的正确位置
- 确认 paired devices 仍然有效
- 保护历史 sessions / transcript，不轻易 cleanup
- 通过真实消息通道验证迁移成功
这一步完成后，OpenClaw 才真正从“文件已经迁过去”进入“新主机可以稳定接管”的状态。
迁移后修复的核心经验是：不要只看服务是否 active，也不要只看文件是否存在。对 AI 代理系统来说，更重要的是状态引用是否正确、插件是否真正加载、认证是否可持续、历史会话是否保留，以及外部消息链路是否能完成一次真实闭环。