OpenClaw

Install context-mode in OpenClaw as a native gateway plugin via the dedicated installer, owning compaction as a context engine.

OpenClaw is an agent gateway, and context-mode ships as a native gateway plugin. Instead of running a separate MCP server process, the plugin registers its hooks directly through the gateway plugin API and also registers as a context engine — so it owns compaction rather than reacting to it from the outside.

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, installs the plugin, and reloads the gateway if it is running.

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 started at least once before you run the installer. The script needs an existing OpenClaw state directory containing an openclaw.json config file; if neither exists it stops and asks you to start OpenClaw first.

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: it builds the project, rebuilds the native better-sqlite3 module, installs the plugin under <state-dir>/extensions/context-mode/, registers context-mode in openclaw.json, and reloads the gateway if it is running.

npm run install:openclaw

The installer writes state under the OpenClaw state directory, which defaults to /openclaw. To target a different location, set OPENCLAW_STATE_DIR to an existing OpenClaw state directory (the one that already holds your openclaw.json):

OPENCLAW_STATE_DIR=/path/to/state npm run install:openclaw

With the default, the plugin is installed under /openclaw/extensions/context-mode/; with an override, paths are relative to whatever OPENCLAW_STATE_DIR points to (for example ~/.openclaw/extensions/context-mode/).

Confirm the gateway reloaded

If a gateway process is running, the installer signals it to reload so the plugin goes live, and prints a confirmation. If no gateway is running, the installer instead tells you to start one manually (OPENCLAW_STATE_DIR=<state-dir> openclaw gateway start). Either way, confirm the gateway is up and serving the registered extension before you continue.

Configure

Configuration lives in openclaw.json under your state directory (for example /openclaw/openclaw.json), where the installer registers context-mode as an enabled plugin and assigns it the context-engine slot so it owns compaction. 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 these gateway hooks:

tool_call:before — PreToolUse equivalent (blocking and arg modification)
tool_call:after — PostToolUse equivalent
command:new — SessionStart equivalent, fires on each new gateway command
before_prompt_build — routing instruction and session-context injection
registerContextEngine — owns compaction (PreCompact equivalent)

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.

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

Verify

The OpenClaw installer builds from source and does not put a context-mode binary on your PATH, so the terminal doctor requires a separate global install (npm install -g context-mode). With that in place, confirm the install with the doctor — it checks language runtimes, the FTS5 knowledge base, and plugin registration, then reports anything that needs attention.

context-mode doctor

A clean run means the gateway plugin is registered and context-mode is ready to route your next data-heavy command.

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