概览

OpenClaw 插件为在 OpenClaw 网关上运行的代理提供 claude-mem 持久内存。它处理三件事：

1. 观察记录 — 从 OpenClaw 的嵌入式运行器捕获工具使用情况，并将其发送到 claude-mem 工作器进行 AI 处理
2. 系统提示上下文注入 — 通过 before_prompt_build 钩子将观察时间线注入每个代理的系统提示中，同时保持 MEMORY.md 可用于代理整理的记忆
3. 观察源 — 通过 SSE 实时将新的观察结果流式传输到消息通道（Telegram、Discord、Slack 等）

OpenClaw 的嵌入式运行器（pi-embedded）直接调用 Anthropic API，而不生成 claude 进程，因此 claude-mem 的标准钩子从未触发。这个插件通过使用 OpenClaw 的事件系统来捕获相同的数据，从而弥补了这一差距。

运作方式

OpenClaw Gateway
  │
  ├── before_agent_start ───→ Init session
  ├── before_prompt_build ──→ Inject context into system prompt
  ├── tool_result_persist ──→ Record observation
  ├── agent_end ────────────→ Summarize + Complete session
  └── gateway_start ────────→ Reset session tracking + context cache
                    │
                    ▼
         Claude-Mem Worker (localhost:37777)
           ├── POST /api/sessions/init
           ├── POST /api/sessions/observations
           ├── POST /api/sessions/summarize
           ├── POST /api/sessions/complete
           ├── GET  /api/context/inject ──→ System prompt context
           └── GET  /stream ─────────────→ SSE → Messaging channels

事件生命周期

When an OpenClaw agent starts, the plugin initializes a session by sending the user prompt to `POST /api/sessions/init` so the worker can create a new session and start processing.


Before each LLM call, the plugin fetches the observation timeline from the worker's `/api/context/inject` endpoint and returns it as `appendSystemContext`. This injects cross-session context directly into the agent's system prompt without writing any files.

The context is cached for 60 seconds to avoid re-fetching on every LLM turn within a session.


Every time the agent uses a tool (Read, Write, Bash, etc.), the plugin sends the observation to `POST /api/sessions/observations` with the tool name, input, and truncated response (max 1000 chars). This is fire-and-forget — it doesn't block the agent from continuing work.

Tools prefixed with `memory_` are skipped to avoid recursive recording.


When the agent completes, the plugin extracts the last assistant message and sends it to `POST /api/sessions/summarize`, then calls `POST /api/sessions/complete` to close the session. Both are fire-and-forget.


Clears all session tracking (session IDs, context cache) so agents get fresh state after a gateway restart.

系统提示上下文注入

该插件通过 OpenClaw 的 before_prompt_build 钩子将跨会话的观察上下文注入到每个代理的系统提示中。内容来自 worker 的 GET /api/context/inject?projects=<project> 端点，该端点从 SQLite 数据库生成格式化的 Markdown 时间线。

这种方法将MEMORY.md保持在代理的控制下，用于策划长期记忆（决策、偏好、持久事实），同时观察时间线通过系统提示传递到其应在的位置。

每个项目的上下文会缓存60秒，以避免在每次LLM交互时重新获取。网关重启时缓存会被清除。使用syncMemoryFileExclude可以完全选择性地让特定代理退出上下文注入。

观察数据流 (SSE → 消息传递)

该插件运行一个后台服务，连接到工作人员的 SSE 流（GET /stream），并将 new_observation 事件转发到配置的消息通道。这让您可以实时监控您的代理从 Telegram、Discord、Slack 或任何支持的 OpenClaw 通道学到的内容。

SSE 连接使用指数退避（1秒 → 30秒）进行自动重连。

设置观测馈送

每当 claude-mem 创建新的观察时，观察信息流会向您的 OpenClaw 频道发送一个格式化消息。每条消息都包括观察标题和副标题，以便您在代理工作时跟进。

消息在你的频道中看起来是这样的：

🧠 Claude-Mem Observation
**Implemented retry logic for API client**
Added exponential backoff with configurable max retries to handle transient failures

第1步：选择你的频道

观察订阅功能可以与您的 OpenClaw 网关已配置的任何频道一起使用。您需要两条信息：

• 频道类型 — 在 OpenClaw 注册的频道插件名称（例如，telegram、discord、slack、signal、whatsapp、line）

• 目标 ID — 要发送消息的聊天 ID、频道 ID 或用户 ID

  Channel type: telegram

  Target ID: Your Telegram chat ID (numeric). To find it:

  1. Message @userinfobot on Telegram
  2. It will reply with your chat ID (e.g., 123456789)
  3. For group chats, the ID is negative (e.g., -1001234567890)

  "observationFeed": {
    "enabled": true,
    "channel": "telegram",
    "to": "123456789"
  }

  Channel type: discord

  Target ID: The Discord channel ID. To find it:

  1. Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
  2. Right-click the channel → Copy Channel ID

  "observationFeed": {
    "enabled": true,
    "channel": "discord",
    "to": "1234567890123456789"
  }

  Channel type: slack

  Target ID: The Slack channel ID (not the channel name). To find it:

  1. Open the channel in Slack
  2. Click the channel name at the top
  3. Scroll to the bottom of the channel details — the ID looks like C01ABC2DEFG

  "observationFeed": {
    "enabled": true,
    "channel": "slack",
    "to": "C01ABC2DEFG"
  }

  Channel type: signal

  Target ID: The Signal phone number or group ID configured in your OpenClaw gateway.

  "observationFeed": {
    "enabled": true,
    "channel": "signal",
    "to": "+1234567890"
  }

  Channel type: whatsapp

  Target ID: The WhatsApp phone number or group JID configured in your OpenClaw gateway.

  "observationFeed": {
    "enabled": true,
    "channel": "whatsapp",
    "to": "+1234567890"
  }

  Channel type: line

  Target ID: The LINE user ID or group ID from the LINE Developer Console.

  "observationFeed": {
    "enabled": true,
    "channel": "line",
    "to": "U1234567890abcdef"
  }

步骤2：将配置添加到您的网关

在您的 OpenClaw 网关配置中，将 observationFeed 块添加到您的 claude-mem 插件配置中：

{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "observationFeed": {
          "enabled": true,
          "channel": "telegram",
          "to": "123456789"
        }
      }
    }
  }
}

channel 值必须与已经在您的 OpenClaw 网关上配置并运行的通道插件匹配。如果该通道未注册，您将在日志中看到 Unknown channel type: <channel>。

步骤 3：验证连接

启动网关后，检查数据源是否已连接：

1. 检查日志 — 你应该会看到：

   [claude-mem] Observation feed starting — channel: telegram, target: 123456789
   [claude-mem] Connecting to SSE stream at http://localhost:37777/stream
   [claude-mem] Connected to SSE stream

2. 使用状态命令 — 在任何 OpenClaw 聊天中运行 /claude_mem_feed 查看：

   Claude-Mem Observation Feed
   Enabled: yes
   Channel: telegram
   Target: 123456789
   Connection: connected

3. 触发测试 — 让一个代理执行一些工作。当Worker 将工具使用处理为观察结果时，你将在已配置的频道中收到一条消息。

该 feed 只发送 new_observation 事件——而不是原始工具使用情况。观察结果由Worker的 AI 代理异步生成，因此在使用工具和观察消息出现在您的频道之间会有 1-2 秒的延迟。

源源故障排除

症状	原因	解决方法
Connection: disconnected	Worker 未运行或端口错误	检查 workerPort 配置，运行 npm run worker:status
Connection: reconnecting	Worker 正在运行，但连接中断	插件会自动重连并带有退避机制 — 最多等待 30 秒
Unknown channel type 在日志中	网关上未加载频道插件	请确认您的 OpenClaw 网关已配置频道插件
没有消息显示	源连接但未创建任何观察	检查代理是否正在运行以及工作进程是否正在处理观察
日志中的 Observation feed disabled	enabled 是 false 或缺失	将 observationFeed.enabled 设置为 true
日志中的 Observation feed misconfigured	缺少 channel 或 to	需要同时提供 channel 和 to

安装

运行这个一行命令以自动安装所有内容：

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

安装程序负责处理依赖项检查（Bun、uv）、插件安装、内存槽配置、AI 提供商设置、Worker 进程启动，以及可选的观察馈送配置。

您还可以预先选择选项：

# With a specific AI provider
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY

# Fully unattended (defaults to Claude Max Plan)
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive

# Upgrade existing installation
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade

手动配置

将 claude-mem 添加到您的 OpenClaw 网关的插件配置中：

{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "syncMemoryFile": true,
        "workerPort": 37777,
        "observationFeed": {
          "enabled": true,
          "channel": "telegram",
          "to": "your-chat-id"
        }
      }
    }
  }
}

claude-mem Worker 服务必须在与 OpenClaw 网关相同的机器上运行。该插件通过 HTTP 在 localhost:37777 上与其通信。

配置

在内存数据库中进行观察范围定义的项目名称。来自此网关的所有观察将存储在此项目名称下。

通过 before_prompt_build 钩子将观察上下文注入代理系统提示。当 true 时，代理会自动接收跨会话上下文。设置为 false 可完全禁用上下文注入（观察仍会被记录）。

代理ID被排除在自动上下文注入之外。适用于管理自己记忆且不需要观察时间线的代理（例如，["snarf", "debugger"]）。排除的代理仍会记录观察，只是跳过上下文注入。

claude-mem Worker 服务的端口。如果你的 Worker 进程运行在非默认端口，请覆盖此设置。

启用实时观察流向消息频道。

通道类型：telegram，discord，signal，slack，whatsapp，line

要发送观测结果的目标聊天/用户/频道ID。

命令

/claude_mem_feed

显示或切换观测源状态。

/claude_mem_feed        # Show current status
/claude_mem_feed on     # Request enable
/claude_mem_feed off    # Request disable

/claude_mem_status

检查 Worker 健康和会话状态。

/claude_mem_status

返回工作状态、端口、活动会话数和观察数据连接状态。

架构

该插件使用 HTTP 调用已运行的 claude-mem Worker 服务，而不是生成子进程。这意味着：

• 网关不需要 bun 依赖
• 每个事件无进程生成开销
• 使用与 Claude Code 钩子相同的 Worker API
• 所有操作都是非阻塞的（在适用场景下采用即发即忘）

会话跟踪

每个 OpenClaw 代理会话都会获得一个唯一的 contentSessionId（格式：openclaw-<sessionKey>-<timestamp>），该 contentSessionId 会映射到 Worker 进程中的 claude-mem 会话。插件会跟踪：

• sessionIds — 将 OpenClaw 会话密钥映射到内容会话 ID
• contextCache — 用于上下文注入响应的 TTL 缓存（60秒），按项目键控

两者都已在gateway_start上清除。

要求

• Claude-mem Worker 服务正在 localhost:37777（或配置端口）上运行
• 支持插件的OpenClaw网关
• 网关与工作节点之间的网络访问（仅本地主机）