OpenClaw 接入 Honcho 记忆系统：Docker Compose 自托管与配置

OpenClaw 自带的 MEMORY.md 适合保存明确、稳定的工作区知识，但随着对话增多，它很难自然地处理「我有哪些偏好」「上一次这个项目进行到哪里」「不同渠道里提到过什么」这类长期上下文。

Honcho 是一个面向 Agent 的记忆服务。它会持续保存会话，并为用户和 Agent 分别建立模型；OpenClaw 通过官方插件接入后，可以在 WhatsApp、Telegram、Discord、Slack 等不同渠道间复用同一份长期记忆。本文记录一套以 Docker Compose 自托管 Honcho、再接入 OpenClaw 的完整流程。

本文以 Linux 服务器为例。命令中的 localhost 指 Honcho 服务所在的主机；若 OpenClaw 与 Honcho 不在同一台机器或同一个容器网络中，必须替换为 OpenClaw 实际可访问的地址。

先分清：Honcho 不是单纯的向量库

向量数据库主要解决「按语义找回相似片段」；Honcho 在此之上还会从对话中持续归纳信息，形成用户和 Agent 的表示模型。

OpenClaw 插件的工作流程可以简化为：

用户与 Agent 正常对话。
每个 AI 回合结束后，插件把用户和 Agent 的消息写入 Honcho。
Honcho 根据历史会话维护总结、结论和用户偏好。
OpenClaw 在构建下一轮提示词前，通过插件注入相关上下文；Agent 也可按需调用 Honcho 工具检索细节。

因此它既能回答「我偏好什么风格」，也能找回「上次关于某个项目做了什么决定」。官方插件提供的常用工具包括：

工具	用途
`honcho_context`	读取跨会话的用户表示，`card` 适合快速了解，`full` 适合查看完整上下文。
`honcho_search_conclusions`	对已归纳的结论做语义搜索。
`honcho_search_messages`	按内容、发送者、日期等条件搜索历史消息。
`honcho_session`	查询当前会话的历史和摘要。
`honcho_ask`	让 Honcho 基于用户记忆回答问题；适合需要综合判断的场景。

OpenClaw 需要配置什么

OpenClaw 的 Honcho 插件主要配置三项：

apiKey：使用 Honcho 托管服务时填写；自托管时可以省略。
workspaceId：记忆隔离空间。不同环境或不同用户建议使用不同值。
baseUrl：Honcho API 地址。托管服务使用默认地址，自托管时填写自己的服务地址。

除此之外，插件会负责会话写入、上下文检索和提示词注入，不需要额外配置记忆更新策略。

1. 用 Docker Compose 自托管 Honcho

自托管的好处是记忆数据、数据库和服务进程都在自己的机器上。Honcho 的 Docker Compose 会一起编排 API、数据库、Redis 和负责派生记忆的后台进程。

先获取官方仓库并准备配置文件：

git clone https://github.com/plastic-labs/honcho.git
cd honcho

cp .env.template .env
cp docker-compose.yml.example docker-compose.yml

编辑 .env，至少为 Honcho 的派生任务配置一个可用的 LLM Provider 凭据，例如 OpenAI、Anthropic 或 Gemini 的 API Key。这个 LLM 用于从对话中归纳结论和用户模型；只有 API 服务而没有可用的派生模型，记忆写入后也难以形成高质量长期结论。

启动服务：

docker compose up -d --build

-d 表示在后台运行。无论使用命令行、1Panel 还是 Portainer 管理 Docker，首先都应该确认服务健康，而不是只看容器是否创建成功：

# 查看容器状态
docker compose ps

# API 健康检查
curl http://localhost:8000/health

# 确认负责派生记忆的进程正在轮询或处理任务
docker compose logs deriver --tail 20

健康检查成功且 deriver 日志有正常轮询或处理记录，才说明本地 Honcho 后端已经具备可用条件。

2. 安装 OpenClaw Honcho 插件

在运行 OpenClaw 的环境中执行：

openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force

openclaw honcho setup 会交互式写入配置，并检测是否存在旧的工作区记忆文件。自托管时：

API Key 留空。
Base URL 填入 Honcho API 地址，例如 http://localhost:8000。
为当前 OpenClaw 实例指定一个清晰且稳定的 workspaceId，例如 home-openclaw。

如果 OpenClaw 本身运行在容器内，localhost 会指向 OpenClaw 容器自身，并不是宿主机。此时需要将两者放入同一 Docker 网络并使用服务名，或使用宿主机可达地址。最简单的验证方式是进入 OpenClaw 所在的运行环境后执行：

curl http://<honcho-host>:8000/health

这一步能够排除大多数「后台服务已经启动，但 OpenClaw 无法使用」的问题。

3. 手动检查配置文件

向导执行后，配置会写在 ~/.openclaw/openclaw.json 的 plugins.entries["openclaw-honcho"].config 下。自托管的最小配置类似下面这样：

{
  plugins: {
    entries: {
      "openclaw-honcho": {
        config: {
          workspaceId: "home-openclaw",
          baseUrl: "http://localhost:8000",
          // 自托管时省略 apiKey
        },
      },
    },
  },
}

使用 Honcho 托管服务时则保留默认 baseUrl，并填入 apiKey。workspaceId 是记忆的隔离边界：开发、生产或不同用户应使用不同值，避免互相污染上下文。

4. 迁移已有的 Markdown 记忆

首次运行 openclaw honcho setup 时，插件会发现已有的记忆文件并询问是否迁移。可迁移内容包括：

描述用户的信息：USER.md、IDENTITY.md、MEMORY.md、memory/、canvas/。
描述 Agent 自身的信息：SOUL.md、AGENTS.md、TOOLS.md、BOOTSTRAP.md。

迁移是非破坏性的：文件会上传给 Honcho，源文件不会被删除或移动。建议先迁移，再保留本地 Markdown 作为人工可读的基线资料。对于项目文档、操作手册等仍以文件为主的知识，保留 OpenClaw 的本地记忆或 QMD 搜索会更合适。

5. 用命令验证记忆链路

配置完成后，按顺序检查：

# 检查插件和服务连接状态
openclaw honcho status

# 让 Honcho 根据已有记忆回答一个问题
openclaw honcho ask "我通常偏好怎样的回答风格？"

# 对历史记忆进行语义检索
openclaw honcho search "部署 Docker Compose 的注意事项" -k 5