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 需及时跟进维护。