核心用法
honcho-setup 是 OpenClaw 生态的记忆系统迁移工具，用于将传统基于 Markdown 文件的记忆架构（USER.md、MEMORY.md、memory/ 目录等）无缝迁移至 Honcho 智能记忆 API。执行流程分为七个严格阶段：
1. 插件安装：通过 openclaw plugins install @honcho-ai/openclaw-honcho 安装官方插件
2. 连接验证：支持两种模式——托管模式（需 HONCHO_API_KEY，默认连接 api.honcho.dev）或本地自托管（通过 HONCHO_BASE_URL 指向私有实例）
3. 文件扫描：自动识别 9 类记忆文件及 memory/、canvas/ 目录内容
4. 数据上传：使用 Honcho SDK 的 session.uploadFile() 接口，区分用户文件（owner peer）与智能体文件（openclaw peer）
5. 安全归档：所有文件强制备份至 {workspace_root}/archive/ 后才允许删除原文件
6. 文档更新：将 SOUL.md、AGENTS.md、BOOTSTRAP.md 中的旧式文件引用替换为 Honcho 工具（honcho_profile、honcho_context、honcho_search、honcho_recall、honcho_analyze）
显著优点
- 双重模式灵活部署：既可用托管云服务零运维启动，也可完全自托管掌控数据主权
- 零数据丢失保障：强制归档机制确保任何删除操作前必有可验证的备份副本
- 精细权限控制：两次显式用户确认（上传前、归档前），完整披露目标 URL 与文件清单
- 敏感信息最小化：仅读取
HONCHO_API_KEY单个环境变量，不触碰其他配置 - 开源透明：Honcho SDK 与插件代码完全开源，无隐藏行为
潜在局限
- 网络依赖：托管模式必须连接外部 API，离线环境仅限自托管方案
- 迁移单向性：设计为从文件系统迁出，无内置回滚至纯文件模式的机制
- Node 生态锁定：依赖 Node.js/npm 环境，对纯 Python 或其他运行时用户增加栈复杂度
- 手动冲突处理：若 archive/ 目录存在同名文件，自动追加时间戳，需用户后续手动整理
适合人群
- 已在使用 OpenClaw 文件式记忆、希望升级至结构化 API 记忆的用户
- 需要 AI 智能体长期记忆持久化与跨会话上下文的开发者
- 对数据隐私敏感、希望选择自托管方案的企业或团队
- 愿意接受托管服务便捷性以换取运维成本的个人开发者
常规风险
| 风险类别 | 具体说明 | 缓解措施 |
|---------|---------|---------|
| 数据外泄 | 用户记忆内容上传至第三方 API | 强制确认流程 + 自托管选项 + 仅传输必要文件 |
| 误删数据 | 迁移失败可能导致文件丢失 | 先归档验证、后删除；上传失败则中止全流程 |
| 凭证泄露 | API Key 被不当读取 | 仅读取单个指定变量，不解析整个 .env 文件 |
| 服务依赖 | 托管服务可用性影响功能 | 支持完全离线自托管，消除外部依赖 |
> 关键安全承诺：此技能绝不执行无备份的删除操作，绝不在用户确认前上传任何数据，绝不多读取任何非必要的配置信息。