OpenClaw

Install context-mode in OpenClaw as a native gateway plugin via the dedicated installer, with an MCP sidecar and registration as the context engine for compaction-aware session resume.

OpenClaw is an OpenAI-stack agent gateway, and context-mode ships as a native gateway plugin targeting Pi Agent sessions. Two registrations work together:

Gateway plugin — registers its routing and lifecycle hooks in-process through the gateway plugin API, and registers as the context engine. It captures compaction events for session resume, while OpenClaw itself still performs the actual conversation truncation.
MCP sidecar (mcp.servers.context-mode) — spawns the bundled server.bundle.mjs so the agent-callable ctx_* tools also appear in the Pi Agent tool list.

Installation uses a dedicated installer rather than a global npm install. You obtain the source and run a single script that builds, rebuilds the native module, registers the plugin and the MCP sidecar, and restarts the gateway.

context-mode runs 100% locally with zero telemetry. The sandbox, indexing, and search all stay on your machine.

Prerequisites

OpenClaw must already be installed and the gateway running before you run the installer.

Requirement	Why
OpenClaw installed, gateway running	Both must be in place before you run the installer.
OpenClaw newer than `2026.1.29`	The native gateway plugin hooks (`api.on()`) need it. On older versions the lifecycle hooks silently fail and context-mode falls back to DB snapshot reconstruction.
Node.js 22.5.0 or newer	Required for the sandbox and FTS5 knowledge base.

Install

Get the source

Obtain the context-mode source. The installer builds from source and rebuilds the native module that the gateway loads, so you need the full checkout rather than a published package.

git clone https://github.com/mksglu/context-mode.git
cd context-mode

Run the OpenClaw installer

Run the dedicated installer. It does everything end to end: npm install, npm run build, the native better-sqlite3 rebuild, plugin and MCP-sidecar registration in openclaw.json, and a gateway restart via SIGUSR1.

npm run install:openclaw

The installer is bash-only — it requires Git Bash or WSL on Windows and exits with an error on native Windows.

The installer reads $OPENCLAW_STATE_DIR from your environment and defaults to /openclaw. To target a different state directory, pass it as a positional argument:

npm run install:openclaw -- /path/to/openclaw-state

State directory by environment:

Environment	State directory
Docker	`/openclaw` (the default)
Local	`~/.openclaw`, or wherever you set `OPENCLAW_STATE_DIR`

The plugin is installed under <state-dir>/extensions/context-mode/.

Open a Pi Agent session

The installer restarts the gateway via SIGUSR1 so the plugin and the MCP sidecar go live. Open a Pi Agent session (Read/Write/Edit/Bash tools) and confirm the ctx_* tools appear in the tool list before you continue. There are 11:

ctx_execute
ctx_execute_file
ctx_index
ctx_search
ctx_fetch_and_index
ctx_batch_execute
ctx_stats
ctx_doctor
ctx_upgrade
ctx_purge
ctx_insight

They are exposed two ways:

The plugin registers them in-process via api.registerTool().
The MCP sidecar spawns server.bundle.mjs to surface them to the agent's tool list.

Configure

Configuration lives in openclaw.json under your state directory (for example /openclaw/openclaw.json). The installer makes several edits there:

adds context-mode to plugins.allow
registers plugins.entries["context-mode"] = { enabled: true }
assigns the context-engine slot (plugins.slots.contextEngine = "context-mode")
registers the MCP sidecar as mcp.servers["context-mode"] = { command: "node", args: ["<root>/server.bundle.mjs"] }
removes any legacy plugins.load.paths entry to prevent duplicate registration

Routing instructions are read from AGENTS.md, and session state is stored under <state-dir>/context-mode/sessions/. You rarely need to edit any of this by hand.

The plugin registers its tool and lifecycle hooks in-process through api.on():

Hook	Role
`before_tool_call`	PreToolUse equivalent (blocking and arg modification)
`after_tool_call`	PostToolUse equivalent
`session_start` / `session_end`	SessionStart equivalent, plus a final resume snapshot at session end
`before_compaction` / `after_compaction` plus `registerContextEngine`	PreCompact equivalent. context-mode registers as the context engine and captures compaction events for resume, but the engine declares `ownsCompaction: false` and defers the actual truncation to OpenClaw
`before_prompt_build`	Routing instruction and session-context injection
`before_model_resolve`	User-message capture
`subagent_spawning`	Routing-block injection into subagents

It also registers, through two further APIs:

Gateway command hooks — command:new, command:reset, and command:stop via api.registerHook(), for per-command session init and cleanup.
Auto-reply slash commands — ctx-stats, ctx-doctor, and ctx-upgrade via api.registerCommand().

The two registration APIs take different name forms, and they are not interchangeable. Lifecycle and tool hooks use api.on() with the underscore names above (before_tool_call, after_tool_call, session_start, ...). Command hooks use api.registerHook() with the colon names (command:new, command:reset, command:stop). Calling api.registerHook('before_tool_call') with the wrong API registers silently but never fires.

Output modification is not available in the gateway plugin paradigm — the API exposes tool arguments and context, not the rendered tool output. Blocking, arg modification, and context injection are fully supported. An ask decision is converted to block (with the original reason) since the gateway has no interactive confirmation path.

See /docs/configuration for the full list of environment variables, storage paths, and permission rules.

Verify your savings

Confirm context-mode is actually saving you tokens, not just installed:

In a Pi Agent session, type ctx stats in chat to read the context-saved ratio and per-tool token breakdown for the session. After a few routed tool calls it should climb toward ~98%, which also confirms the MCP sidecar's ctx_* tools are loaded.
Run context-mode doctor in your terminal to confirm the plugin is registered under plugins.entries, is enabled, and holds the context-engine slot (plugins.slots.contextEngine = context-mode). If openclaw.json cannot be read, the doctor reports a single failure instead. A failed check prints the fix context-mode upgrade.

context-mode doctor

A clean doctor run plus a climbing ctx stats savings ratio means the gateway plugin is registered and context-mode is routing your data-heavy commands into the sandbox.

Troubleshooting

openclaw.json not found — OpenClaw creates this file on first launch. Start OpenClaw once (openclaw gateway start), then re-run the installer. This is the most common issue for users who install context-mode before ever starting OpenClaw.

Plugin installed but not loading — clear the jiti cache (rm -f /tmp/jiti/context-mode-*.cjs) and restart the gateway. If it persists, verify the plugin appears in openclaw plugins list.

Plugin loads but ctx_* tools are missing — the tools live in the MCP sidecar. Verify it is registered with openclaw mcp list, and add it if missing (command below).

openclaw mcp set context-mode \
  "{\"command\":\"node\",\"args\":[\"/absolute/path/to/context-mode/server.bundle.mjs\"]}"
openclaw gateway restart

Re-running the installer manually — the installer is just a bash script; you can run it directly and pass a state directory: bash scripts/install-openclaw-plugin.sh /path/to/openclaw-state.

Pi

A related host that runs context-mode as a hook-capable extension.

Configuration

Environment variables, storage, and permission rules.

Pi

Configuration

On this page