OpenClaw integration
The OpenClaw integration gives agents on an OpenClaw gateway persistent Claude-Mem memory. It connects OpenClaw events to the Claude-Mem worker so agents can reuse past context, record new work, search memory, and optionally send new observations to a messaging channel. It is the OpenClaw-specific child of the broader agent integrations and distribution model.
Integration model
OpenClaw runs an embedded agent and exposes its own plugin events. The integration uses that native plugin boundary instead of Claude Code hook files, while keeping the worker-facing memory meaning aligned with the other adapters described in plugin hooks and agent modes.
Host boundary
The OpenClaw plugin is a memory plugin named claude-mem. OpenClaw owns agent execution, commands, and message delivery. Claude-Mem owns session memory, observation processing, context generation, and the live observation stream. The two systems communicate through the worker's HTTP interface.
This boundary matters because OpenClaw's embedded runner does not start a separate claude process. OpenClaw must therefore provide the events that the plugin uses to capture work and add memory back to the agent prompt.
References: openclaw/openclaw.plugin.json• L1-14 openclaw/…/index.ts• L99-131 openclaw/…/index.ts• L620-640
Memory slot
OpenClaw has one active memory slot. Installation assigns that slot to claude-mem and enables the matching plugin entry. This lets Claude-Mem provide automatic context without replacing the agent's own MEMORY.md file.
The project setting separates observations from different gateways or use cases. Agent-specific projects use the openclaw-<agent-id> form, so a shared gateway can keep each agent's memory distinct while still reading the base project context.
References: src/…/OpenClawInstaller.ts• L92-126 openclaw/…/index.ts• L627-640 openclaw/openclaw.plugin.json• L41-45
Plugin contract
The plugin contract joins OpenClaw configuration to the worker location and the memory behavior that users see. The manifest defines the accepted settings, while the runtime uses those settings for prompt context, project scope, worker access, and optional message delivery.
Configuration surface
The main settings are:
| Setting | Purpose | Default or constraint |
|---|---|---|
syncMemoryFile | Adds Claude-Mem context to the agent system prompt. | Enabled by default. It does not write MEMORY.md. |
syncMemoryFileExclude | Excludes selected agent IDs from prompt injection. | Empty list. Observation capture continues for excluded agents. |
workerPort | Selects the worker HTTP port. | 37777. |
workerHost | Selects the worker host. | 127.0.0.1; use a reachable host when the gateway and worker run in different environments. |
project | Scopes observations and context. | openclaw. |
observationFeed | Enables the optional live feed. | Disabled unless explicitly enabled. It needs both channel and to. |
The feed also accepts an optional Telegram bot token and emoji rules for source labels. The manifest advertises Telegram, Discord, Signal, Slack, WhatsApp, and LINE as channel types. The target value is the channel, chat, or user ID expected by the selected OpenClaw channel.
References: openclaw/openclaw.plugin.json• L14-105 openclaw/…/index.ts• L172-185 openclaw/…/index.ts• L893-917
Worker interface
The worker is the shared memory service behind the OpenClaw adapter. The plugin uses it for session initialization, observation submission, prompt context, session summaries, health checks, memory search, recent context, and timeline lookup.
The important contract is directional:
- OpenClaw sends session starts and tool results to the worker.
- The worker returns formatted context for prompt injection.
- The worker returns search, recent-context, timeline, and health data for OpenClaw commands.
- The worker emits processed observations through its server-sent event stream for the optional feed.
The plugin treats most capture and summary calls as non-blocking. A worker outage must not stop the OpenClaw agent from continuing its main task. Repeated failed requests open a short circuit and pause more requests until the worker can be probed again.
References: openclaw/…/index.ts• L243-397 openclaw/…/index.ts• L721-768 openclaw/…/index.ts• L797-861
Session lifecycle
The session lifecycle turns OpenClaw activity into Claude-Mem records and turns stored records back into agent context. The plugin keeps one Claude-Mem content session for the OpenClaw session identity, including aliases supplied by the gateway.
The following diagram shows the main event path between OpenClaw, the worker, and the agent prompt.
flowchart LR
A[OpenClaw agent starts] --> B[Initialize worker session]
B --> C[Agent prompt is built]
C --> D[Fetch project context]
D --> E[Append context to system prompt]
E --> F[Agent uses tools]
F --> G[Record tool result]
G --> F
F --> H[Agent ends]
H --> I[Summarize session]
I --> J[Clear local session tracking]
Session events
OpenClaw initializes a worker session at session start, after compaction, or before an agent run. A short duplicate guard prevents one user turn from creating repeated prompt records. When the agent ends, the plugin sends the last assistant message for summarization. Gateway and session end events clear local tracking so later work does not reuse stale session state.
References: openclaw/…/index.ts• L641-716 openclaw/…/index.ts• L747-785 openclaw/…/index.ts• L836-876
Prompt context
Before a prompt is sent to the model, the plugin asks the worker for context from the configured base project and the current agent project. It appends that context to the system prompt and caches it for 60 seconds. Setting syncMemoryFile to false, or listing an agent in syncMemoryFileExclude, skips this injection but does not stop observation capture.
This keeps MEMORY.md available for agent-curated durable facts. The observation timeline remains a separate stream of working memory supplied by the integration.
References: openclaw/…/index.ts• L649-654 openclaw/…/index.ts• L718-745 openclaw/…/index.ts• L787-795 openclaw/…/index.test.ts• L528-760
Observation capture
Each persisted tool result becomes a worker observation with its tool name, input, response text, and workspace. The integration skips tools whose names begin with memory_ to avoid recording its own memory lookups. It limits captured response text so large tool output does not dominate the memory request.
Observation capture is separate from prompt injection. An excluded agent still contributes to the shared memory store, even though it does not receive automatic context.
References: openclaw/…/index.ts• L797-834 openclaw/…/index.test.ts• L355-413 openclaw/…/index.test.ts• L606-663
Observation feed
The observation feed is an optional monitoring path from the worker's live stream to an OpenClaw messaging channel. It reports processed new_observation events rather than raw tool calls, so the message appears after the worker turns activity into a structured observation.
Stream delivery
When enabled and fully configured, the plugin opens a server-sent event connection to the worker. It formats each new observation and sends it through the selected OpenClaw channel. The connection reports connected, reconnecting, or disconnected state and retries with increasing delays after a failure.
Routine observations use a compact message. Important types such as bug fixes and decisions can include narrative, facts, and concepts. This keeps normal channel traffic short while preserving more detail for events that need attention.
References: openclaw/…/index.ts• L399-459 openclaw/…/index.ts• L526-618 openclaw/…/index.test.ts• L762-1018
Channel delivery
The host remains responsible for sending messages. The plugin maps a configured channel name to the corresponding OpenClaw runtime sender, then passes the configured target and formatted text. A dedicated Telegram bot token is an optional path that sends directly to Telegram instead of using the gateway channel.
The feed does not start when enabled is false or when either channel or to is missing. A channel name that is not available in the gateway runtime produces a warning and no message.
References: openclaw/…/index.ts• L451-524 openclaw/…/index.ts• L882-930 openclaw/openclaw.plugin.json• L46-101
User commands
OpenClaw exposes memory actions as chat commands. These commands keep the OpenClaw user interface small while the worker remains responsible for memory data and search rules.
Memory commands
The command surfaces are:
| Command | Role |
|---|---|
/claude_mem_status | Checks worker health, port, active local sessions, and feed state. |
/claude_mem_feed | Shows feed configuration and connection state. on and off report a requested config change; persistent state still comes from plugin configuration. |
/claude-mem-search <query> [limit] | Searches observations and displays a short result list. |
/claude-mem-recent [project] [limit] | Shows recent session and observation counts for a project. |
/claude-mem-timeline <query> [depthBefore] [depthAfter] | Finds a matching memory and displays nearby timeline events. |
These commands are useful for checking the integration without opening the worker viewer. They also make worker failures visible as user-facing responses instead of silent empty results.
References: openclaw/…/index.ts• L933-1133 openclaw/…/index.test.ts• L168-220 openclaw/…/index.test.ts• L466-500
Installation lifecycle
OpenClaw can receive the integration through the hosted setup script or through the package's host installer. Both paths place an OpenClaw plugin beside the gateway and connect it to the worker, but they differ in how they obtain and register the plugin.
Hosted setup
openclaw/install.sh is the end-to-end setup path. It checks or installs Bun and uv, locates the OpenClaw gateway, clones and builds the OpenClaw package, installs and enables the plugin through the OpenClaw CLI, configures the memory slot, writes Claude-Mem settings, starts or reuses the worker, and optionally writes feed settings.
Interactive setup can select Claude, Gemini, or OpenRouter. Non-interactive setup selects Claude by default and skips feed setup. Upgrade mode keeps the installed integration and updates settings without repeating the full clone and registration path.
References: openclaw/install.sh• L1-51 openclaw/install.sh• L596-764 openclaw/install.sh• L766-834 openclaw/install.sh• L1495-1651
Package installation
The package-side installer looks for a pre-built OpenClaw bundle, copies it into ~/.openclaw/extensions/claude-mem, copies the manifest and skills, writes the small OpenClaw package descriptor, and registers the plugin in ~/…/openclaw.json. It preserves existing Claude-Mem plugin settings when they already exist and removes the extension and registration during uninstall.
This path is used by the broader installation and npx CLI flow described in installation and npx CLI. After either installation path, the gateway must restart before it can load the plugin. The worker must also be reachable at the configured host and port.
References: src/…/OpenClawInstaller.ts• L16-71 src/…/OpenClawInstaller.ts• L92-142 src/…/OpenClawInstaller.ts• L145-239 src/…/OpenClawInstaller.ts• L287-309
Skills surface
The OpenClaw package exposes two skills: make-plan and do. They guide agents through planning and execution work; they do not replace the memory worker or change the event contract.
Planning skill
The make-plan skill frames a task as a phased plan. It asks for documentation discovery, allowed APIs, verification steps, and anti-pattern checks before implementation. Its purpose is to make a plan that another agent can execute safely.
References: openclaw/…/SKILL.md• L1-67 openclaw/openclaw.plugin.json• L10-13
Execution skill
The do skill executes a phased plan through implementation and verification work. It requires evidence after each phase and keeps commits behind verification. Its purpose is to turn a reviewed plan into controlled changes.
References: openclaw/…/SKILL.md• L1-45 openclaw/openclaw.plugin.json• L10-13
Verification model
Verification checks the integration at three levels: plugin behavior, installer behavior, and gateway behavior. The unit tests use mock worker and channel interfaces to verify the event contract without requiring a live OpenClaw deployment.
Test layers
The package test command compiles the TypeScript runtime and runs the plugin tests. Those tests cover registration, session and observation I/O, context injection, command output, feed delivery, channel selection, and worker failure handling.
The shell installer tests source the installer functions in isolation. They check dependency discovery, config preservation, provider settings, worker health handling, feed configuration, argument parsing, and completion output. The Docker E2E path installs the plugin through the real OpenClaw CLI, starts a mock worker, starts the gateway, and checks plugin discovery, files, health, gateway loading, and SSE activity.
References: openclaw/package.json• L1-20 openclaw/…/index.test.ts• L99-220 openclaw/…/index.test.ts• L224-760 openclaw/…/index.test.ts• L762-1178 openclaw/test-install.sh• L1-41 openclaw/e2e-verify.sh• L26-221 openclaw/TESTING.md• L22-64
Verification commands
Use the smallest check that matches the change:
- Run
npm testinopenclaw/for plugin behavior. - Run ./test-install.sh for installer behavior.
- Run ./test-e2e.sh for installation and gateway behavior in Docker.
- Use
./test-e2e.sh --interactivewhen a maintainer needs to inspect plugin discovery, gateway logs, or the mock stream.
References: openclaw/TESTING.md• L1-18 openclaw/TESTING.md• L66-169 openclaw/test-e2e.sh• L1-40
Change checklist
When these files or sections are changed, remember to consider these:
- Keep openclaw.plugin.json, the runtime configuration type, and installer-created defaults aligned. A new setting is incomplete if the host accepts it but installation does not preserve or create it.
- When a worker endpoint or payload changes, review session initialization, observation capture, prompt injection, summaries, commands, health checks, and the mock worker contract together.
- When an OpenClaw event changes, preserve the session identity shared by initialization, tool observations, prompt context, and summaries.
- When a feed channel changes, update the manifest's advertised values, runtime sender mapping, missing-channel behavior, and feed tests as one contract.
- When plugin files or skills change, keep the pre-built package path, hosted installer copy path, package descriptor, and E2E file checks aligned.
- When worker host or port defaults change, update the plugin schema, installer settings, health checks, feed URL, and user verification output.
- When the memory slot contract changes, check existing plugin entries, allowlists, slot conflicts, and upgrade preservation in both installer paths.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The worker is stopped or the configured host or port is wrong. | Context, search, status, and capture requests fail. The circuit breaker then pauses more worker requests for a cooldown. | Verify the worker health endpoint and keep workerHost and workerPort equal to the reachable worker. |
claude-mem is not the OpenClaw memory slot. | The plugin may load but OpenClaw does not use it as the active memory provider. | Set plugins.slots.memory to claude-mem and enable the matching entry. |
Feed is enabled without both channel and to. | The feed service does not connect. Memory capture still works. | Treat both values as required before enabling the feed. |
| The configured channel is not loaded by OpenClaw. | SSE observations arrive but no message is sent. | Use a channel supported and enabled by the gateway. |
| Prompt injection is disabled or the agent is excluded. | The agent receives no automatic cross-session context. Observations continue to be stored. | Check syncMemoryFile and syncMemoryFileExclude when context is expected. |
| A plugin bundle lacks dist/index.js, its manifest, or its package descriptor. | OpenClaw cannot discover or load the extension. | Run the package and Docker checks that verify the installed files. |
| The gateway is not restarted after installation or config changes. | OpenClaw continues to run the old plugin or feed state. | Restart the gateway, then check the load and feed status messages. |
Key files
| File | Why to read it |
|---|---|
| openclaw/openclaw.plugin.json | Defines the OpenClaw memory-plugin identity, skills, and user-facing configuration contract. |
| openclaw/…/index.ts | Connects OpenClaw events and commands to the worker, context injection, session tracking, and observation feed. |
| src/…/OpenClawInstaller.ts | Shows how the package-side installer copies the extension and updates OpenClaw registration. |
| openclaw/install.sh | Shows the hosted setup flow for dependencies, plugin registration, worker startup, provider settings, and feed setup. |
| openclaw/…/SKILL.md | Defines the planning workflow exposed to OpenClaw agents. |
| openclaw/…/SKILL.md | Defines the controlled execution workflow exposed to OpenClaw agents. |
| openclaw/…/index.test.ts | Demonstrates the runtime contract through mock worker, event, command, feed, and failure checks. |
| openclaw/test-install.sh | Exercises installer decisions and the configuration contracts without a full gateway. |
| openclaw/e2e-verify.sh | Verifies plugin discovery, installed files, worker SSE, and gateway startup in a real OpenClaw container. |
| openclaw/TESTING.md | Explains the unit, smoke, container, and real-gateway verification paths. |