核心用法
honcho-setup 是 OpenClaw 生态专用的记忆系统迁移工具，核心任务是将本地 Markdown 文件形式的记忆体系（USER.md、MEMORY.md、memory/、canvas/ 等）完整迁移至 Honcho API，从而用结构化、可检索的 API 替代传统的文件读写。
执行流程
1. 插件安装：通过 openclaw plugins install @honcho-ai/openclaw-honcho 获取官方插件，必要时手动修复依赖
2. 连接验证：区分托管模式（需 HONCHO_API_KEY）与自托管模式（需 HONCHO_BASE_URL），验证网络连通性
3. 文件扫描：递归检测 9 类目标文件及 memory/、canvas/ 目录，生成带体积的清单
4. 上传迁移：调用 session.uploadFile API，用户文件归 owner peer、Agent 配置归 openclaw peer
5. 本地归档：强制备份至 {workspace}/archive/，验证成功后删除 legacy-only 文件
6. 文档更新：将 SOUL.md、AGENTS.md、BOOTSTRAP.md 中的文件读写指令替换为 Honcho 工具（honcho_profile、honcho_context 等）
显著优点
- 双模部署：官方托管（api.honcho.dev）与开源自托管（Docker Compose）灵活切换，后者实现数据完全自主
- 安全冗余：任何删除操作前强制本地归档，支持带时间戳的重复文件命名
- 细粒度权限：仅读取必要的 HONCHO_API_KEY，不扫描 .env 其他变量；上传前双重确认（文件清单+目标 URL）
- 零停机迁移：失败自动回滚，上传异常则中止归档与删除，防止数据丢失
潜在局限
- 网络依赖：托管模式强制外连 api.honcho.dev，无法离线执行
- 敏感数据出境：默认上传用户画像、记忆内容至第三方云，合规场景需切换自托管
- 不可逆操作：legacy-only 文件（USER.md、IDENTITY.md 等）删除后仅保留本地归档，无自动回滚机制
- Node 生态绑定：依赖 npm 安装插件，纯 Python/Rust 环境需额外工具链
适合人群
- 已使用 OpenClaw 且记忆文件膨胀、检索困难的进阶用户
- 希望将 Agent 记忆持久化到数据库而非 Git 仓库的团队
- 对数据主权敏感、愿意自建 Honcho 实例的隐私优先用户
常规风险
| 风险点 | 等级 | 说明 |
|--------|------|------|
| 数据外泄 | 中 | 托管模式下记忆内容上传至第三方，需评估隐私政策 |
| 误删文件 | 低 | 虽有归档验证，但用户若忽略确认步骤仍可能丢失工作区 |
| 凭证泄露 | 低 | .env 读取范围被严格限制，但密钥仍需妥善保管 |
| 服务可用性 | 中 | 托管 API 故障或网络抖动将导致迁移中断 |
官方资源：https://honcho.dev | 开源地址：https://github.com/plastic-labs/honcho