honcho-setup

核心用法

honcho-setup 是一个 OpenClaw 生态的迁移工具，用于将传统的基于 Markdown 文件的 AI 记忆系统（USER.md、MEMORY.md、memory/ 目录等）迁移到 Honcho 长期记忆 API。整个流程分为七个步骤：安装并启用 @honcho-ai/openclaw-honcho 插件、验证 Honcho 连接（支持托管云服务和自托管本地实例）、检测遗留记忆文件、上传至 Honcho、归档原始文件、更新工作区文档引用、最终确认完成。

该 skill 支持两种运行模式：托管模式（默认连接 api.honcho.dev，需 API key）和自托管模式（用户配置 HONCHO_BASE_URL，无需 key）。上传时使用 Honcho SDK 的 session.uploadFile API，将用户文件（USER.md、IDENTITY.md 等）归到 owner peer，代理配置文件（SOUL.md、AGENTS.md 等）归到 openclaw peer。

显著优点

完整的安全披露机制：skill 文档包含长达数千字的 Security & Privacy Disclosure，逐条说明数据上传内容、敏感文件访问范围、网络端点、用户控制点，透明度极高。

双重用户确认：Step 3 上传前和 Step 5 归档前均需用户明确确认，且会展示完整文件列表、大小、目的地 URL，杜绝静默操作。

失败安全设计：若上传失败，绝不进行任何归档或删除操作，原始文件保持原状，防止数据丢失。

灵活的部署选项：既可用官方托管服务快速上手，也支持完全离线的 Docker 自托管，满足不同隐私合规需求。

自动备份机制：所有待删除文件先复制到 {workspace_root}/archive/，同名文件自动附加时间戳，确保可回滚。

潜在缺点与局限性

数据上传不可避免：无论托管还是自托管，用户记忆文件（可能含 PII）必须离开本地环境，对极高敏感场景仍是障碍。

依赖外部 SDK：核心功能绑定 @honcho-ai/sdk，若 SDK 出现漏洞或停更，skill 功能受影响。

文件级粒度不足：目前是全量迁移，不支持选择性排除特定文件，用户无法精细控制哪些记忆片段上传。

Node/npm 环境依赖：需要本地具备 Node.js 和 npm 环境，对纯 Python 或其他技术栈用户增加配置负担。

自托管门槛：虽然提供 Docker 方案，但仍需用户自行维护 Postgres 等依赖，运维成本不低。

适合的目标群体

• 使用 OpenClaw 框架且记忆文件膨胀、需要结构化长期记忆的 AI 代理开发者
• 希望将分散的 Markdown 记忆整合到统一 API 的团队
• 对数据主权有要求、愿意自建基础设施的技术型用户（自托管模式）
• 需要快速验证 AI 记忆产品、愿意使用托管服务的个人开发者或初创团队

使用风险

性能风险：大体积 memory/ 或 canvas/ 目录可能导致上传耗时较长，网络中断需重试。

依赖项风险：插件安装后可能因依赖解析失败需手动进入目录执行 npm install，增加故障排查成本。

数据残留风险：虽然本地有归档，但托管模式下数据一旦上传至 Honcho 云服务，删除需遵循对方数据保留策略，非即时彻底清除。

版本兼容性：Honcho SDK 版本迭代可能导致 API 变动，skill 需及时跟进维护。

概述：从本地文件到智能记忆引擎的进化

honcho-setup 是一款专为 OpenClaw 平台设计的记忆系统迁移技能。它的核心使命是将 AI 智能体依赖的传统文件式记忆（如 USER.md、MEMORY.md、memory/ 等目录）无缝、安全地迁移至 Honcho 记忆管理API。Honcho 是一个在 GitHub 上拥有超过 3,300 星标的成熟开源项目（采用 AGPL-3.0 许可），专为 AI 智能体的个性化、上下文记忆和长期信息存储而构建。

核心功能与用法

该技能的运行流程高度结构化和透明，共分为七个步骤。首先，它会指导用户安装并启用 Honcho 插件。接着，它会进行连接验证，这里给用户提供了极大的灵活性：你可以选择使用 Honcho 提供的托管云服务（默认将数据发送至 api.honcho.dev），也可以选择将数据迁移到自己搭建的本地服务上，实现数据的完全掌控。

迁移的核心在于三步。第一步，技能会扫描工作区，精准识别所有待迁移的遗留文件，包括用户画像、身份信息、长期记忆、近期工作内容（canvas/）以及智能体自身的配置文件和角色设定等。它会将所有找到的文件及其大小列表清晰地展示给用户。第二步，在获得用户的显式许可后，它会将这些文件内容通过 Honcho SDK 安全上传，并根据文件属性（用户相关或智能体自身相关）正确分类。第三步，在再次获得用户的显式许可后，它会将原始文件全部备份到一个 archive/ 目录，验证备份成功后，才会清理旧文件，并根据模板更新工作区文档，使其完全适配 Honcho 的工具生态。整个流程中，任何一步失败都会导致后续操作中止，确保数据零丢失。

显著优点

1. 极致的数据安全与透明性：这是该技能最大的亮点。它不隐藏任何行为。从技能文档开头的醒目警告，到操作前必须获得的两次用户显式确认，再到强制性的本地备份流程，每一步都确保了用户对数据的绝对控制权。安全认证报告也证实了其行为与声明高度一致，无任何后门或隐蔽操作。
2. 灵活的双模式部署：为不同需求的用户提供了最佳选择。普通用户可直接使用官方的托管云服务，享受零运维负担；而对数据隐私和合规性有严格要求的企业或个人，可以通过自托管模式将数据保留在私有环境中。
3. 专业的记忆管理升级：迁移完成后，用户的 AI 智能体将从原始、松散的文件读取模式，升级为使用 Honcho 提供的全套专业记忆工具，如 honcho_profile（用户画像）、honcho_context（上下文管理）、honcho_recall（记忆回忆）等，能显著提升 AI 在对话中的连贯性和个性化水平。
4. 依托成熟的开源项目：该技能并非孤立的脚本，而是建立在 Honcho（GitHub 3,300+ Star）这一活跃且受社区信任的开源项目之上，其技术栈和未来发展都值得信赖。

潜在缺点与局限性

1. 依赖外部服务：无论是使用托管云还是自建服务，该技能都引入了对一个新服务（Honcho）的绝对依赖。如果 Honcho 服务或私人服务实例不可用，AI 将丧失其记忆功能，虽然原始文件有备份，但恢复过程需要手动介入。
2. 迁移为一次性操作：此技能的设计是“一次性”的迁移工具，而非一个持续性的同步服务。迁移后，如果需要再次同步文件或回滚，需要依靠 archive/ 目录中的备份。
3. 上传范围固定：该技能设定的待上传文件列表是固定的。如果你的工作区中有其他自定义的、不在其检测范围内的记忆文件，它们将不会被迁移，可能造成记忆的碎片化。
4. 网络依赖性：整个迁移过程需要良好的网络连接，用于下载依赖、克隆代码库（自托管模式）以及上传数据。网络不稳定可能导致操作中断（尽管有失败中止保护）。

适合的目标群体

这款技能明确服务于 OpenClaw 平台的 AI 智能体用户，特别是那些已经积累了较多本地记忆文件，并希望获得更智能、更专业的记忆管理方案的深度用户。它非常适合两种人群：一是追求便捷、信任成熟云服务的个人开发者或小型团队；二是数据安全性要求极高、需要将所有数据控制在私有环境内的企业或研究机构。

使用风险提示

1. 常规上传风险：上传工作区的用户画像和私人记忆到云端，本质上是将隐私数据委托给第三方。尽管 Honcho 是值得信赖的平台，用户依然需要自行评估其隐私政策（honcho.dev/privacy），确保符合个人或公司的数据保护要求。
2. 插件依赖风险：安装的 @honcho-ai/openclaw-honcho 插件可能在未来与 OpenClaw 平台的更新产生兼容性问题，导致技能无法使用或需要手动修复。
3. 操作中断风险：尽管有多重保护，但在极端情况下（如系统崩溃、强制关机），精确发生在备份验证后、删除原文件前的一瞬间，仍有可能导致数据状态不一致。不过，这种风险发生的概率极低。

结论：honcho-setup 是一款设计精巧、安全性堪称典范的 AI 记忆迁移工具。它在提供强大功能的同时，将数据控制权毫无保留地交到了用户手中，所有风险均被提前识别并有效控制，是 OpenClaw 生态中一次出色的记忆管理升级实践。