# How context-mode Integrates with OpenClaw as a Native Gateway Plugin

> Learn how context-mode integrates with OpenClaw as a native gateway plugin. Discover seamless routing, event capture, and prompt injection for enhanced LLM workflows.

- Repository: [Mert Köseoğlu/context-mode](https://github.com/mksglu/context-mode)
- Tags: how-to-guide
- Published: 2026-04-24

---

**context-mode integrates with OpenClaw by registering as a native plugin via [`openclaw.plugin.json`](https://github.com/mksglu/context-mode/blob/main/openclaw.plugin.json), exposing a `register(api)` function that wires lifecycle hooks to enforce routing rules, capture tool events in SQLite, and inject context snapshots into the LLM prompt.**

The `mksglu/context-mode` repository provides stateful context management for AI agent sessions. It operates as a native OpenClaw gateway plugin by intercepting tool calls, persisting session data, and managing workspace routing without requiring external services.

## Plugin Registration and Initialization

OpenClaw discovers the plugin through the [`openclaw.plugin.json`](https://github.com/mksglu/context-mode/blob/main/openclaw.plugin.json) entry point in the repository root. This manifest declares the extension path and metadata:

```json
{
  "extensions": [
    {
      "id": "context-mode",
      "path": "./src/openclaw-plugin.ts"
    }
  ]
}

```

When OpenClaw starts an agent session, it executes the `register(api)` function exported from [`src/openclaw-plugin.ts`](https://github.com/mksglu/context-mode/blob/main/src/openclaw-plugin.ts). This function receives an **OpenClaw Plugin API** object (`api`) that provides typed lifecycle hooks and command registration.

During initialization (lines 18–38), the plugin resolves the build directory and creates a per-project **SQLite database** via `OpenClawSessionDB`. The database is stored under `~/.openclaw/context-mode/sessions/` and scoped to each project using a SHA-256 hash of the project directory. A singleton pattern ensures all sessions within the same process share the same storage instance.

## Lifecycle Hooks and Session Management

The plugin registers multiple lifecycle hooks via `api.on` and `api.registerHook` to synchronize OpenClaw's ephemeral agent state with persistent SQLite storage.

### Tool Call Interception and Routing

The `before_tool_call` hook (lines 71–93) enforces security and routing rules before any tool executes. It loads the routing module from `hooks/core/routing.mjs` and evaluates whether to **deny**, **ask**, or **modify** the tool call:

```typescript
api.on("before_tool_call", async (ev) => {
  const { routing } = await initPromise;
  const decision = routing.routePreToolUse(
    ev.toolName, 
    ev.params, 
    process.cwd(), 
    "openclaw"
  );
  
  if (decision?.action === "deny") {
    return { block: true, blockReason: decision.reason };
  }
  
  if (decision?.action === "modify") {
    Object.assign(ev.params, decision.updatedInput);
  }
});

```

After the tool executes, the `after_tool_call` hook (lines 84–115) extracts tool-use events via `extractEvents()` and persists them to the session database. It uses `WorkspaceRouter` to resolve the correct session ID from tool parameters, handling OpenClaw-specific tool name mapping before storage.

### Session State and Persistence

The `session_start` hook (lines 46–82) performs a critical **session re-keying** operation. Because the plugin initializes with a temporary session ID before OpenClaw assigns the permanent session identifier, this hook migrates the database records to the final `session_id` using the `session_key` mapping table defined in [`src/adapters/openclaw/session-db.ts`](https://github.com/mksglu/context-mode/blob/main/src/adapters/openclaw/session-db.ts).

The plugin also listens to command hooks (`command:new`, `command:reset`, `command:stop`) to clean up stale sessions and remove workspace registrations when users reset or stop agents.

### Context Compaction and Recovery

To prevent context loss during OpenClaw's conversation compaction, the plugin implements `before_compaction` and `after_compaction` hooks (lines 94–116). The **before** hook writes a resume snapshot to the database via `buildResumeSnapshot()`, while the **after** hook increments the compact count. Later, the `before_prompt_build` hook (priority 10, lines 138–168) re-injects this snapshot into the system prompt, ensuring the LLM retains awareness of previous context after truncation.

## Workspace Routing and Path Resolution

The `WorkspaceRouter` class in [`src/openclaw/workspace-router.ts`](https://github.com/mksglu/context-mode/blob/main/src/openclaw/workspace-router.ts) manages multi-workspace environments by scanning paths for the `/openclaw/workspace-<name>` pattern. It extracts workspace roots and maps them to stable session keys, enabling the plugin to attribute tool events to the correct session when agents operate across multiple directories.

The router provides `resolveSessionId(params, fallback)`, which `after_tool_call` invokes to determine the appropriate database session for storing events based on the tool's working directory or file path parameters.

## Prompt Injection and Routing Instructions

The plugin enhances LLM behavior by injecting content during the prompt building phase. The `before_prompt_build` hook operates at two priority levels:

1. **Priority 10** (lines 138–168): Injects the **resume snapshot** containing previous context and conversation state.
2. **Priority 5** (lines 71–85): Injects optional **routing instructions** loaded from [`configs/openclaw/AGENTS.md`](https://github.com/mksglu/context-mode/blob/main/configs/openclaw/AGENTS.md). This file allows users to define custom rules (e.g., denying specific shell commands) that the model sees before generating tool calls.

Additionally, the `before_model_resolve` hook (lines 131–145) captures the raw user message as a "user_message" event for audit trails.

## Slash Commands and Diagnostics

The plugin exposes three diagnostic commands via `api.registerCommand` (lines 118–176):

- **`/ctx-stats`**: Returns a markdown summary of the current session database statistics and event counts.
- **`/ctx-doctor`**: Runs diagnostic checks on the database and workspace routing configuration.
- **`/ctx-upgrade`**: Handles database schema migrations and plugin updates.

These commands allow users to inspect context-mode state directly within OpenClaw chat sessions without external tools.

## Summary

- **Native Integration**: The plugin loads via [`openclaw.plugin.json`](https://github.com/mksglu/context-mode/blob/main/openclaw.plugin.json) and exports a `register(api)` function in [`src/openclaw-plugin.ts`](https://github.com/mksglu/context-mode/blob/main/src/openclaw-plugin.ts) that receives the OpenClaw Plugin API.
- **Lifecycle Hooks**: Implements `before_tool_call`, `after_tool_call`, `session_start`, compaction hooks, and prompt building hooks to intercept and persist agent behavior.
- **SQLite Persistence**: Uses `OpenClawSessionDB` in [`src/adapters/openclaw/session-db.ts`](https://github.com/mksglu/context-mode/blob/main/src/adapters/openclaw/session-db.ts) with session key mapping to maintain state across OpenClaw's session lifecycle.
- **Workspace Routing**: `WorkspaceRouter` in [`src/openclaw/workspace-router.ts`](https://github.com/mksglu/context-mode/blob/main/src/openclaw/workspace-router.ts) handles multi-workspace path resolution for `/openclaw/workspace-<name>` patterns.
- **Context Recovery**: Injects resume snapshots during `before_prompt_build` to survive conversation compaction, and loads user-defined routing rules from [`configs/openclaw/AGENTS.md`](https://github.com/mksglu/context-mode/blob/main/configs/openclaw/AGENTS.md).

## Frequently Asked Questions

### How does context-mode maintain state across OpenClaw conversation compactions?

The plugin registers `before_compaction` and `after_compaction` hooks that snapshot the current database state using `buildResumeSnapshot()`. When OpenClaw truncates the conversation, the `before_prompt_build` hook (priority 10) retrieves this snapshot and injects it into the system prompt, effectively restoring the previous context for the LLM.

### Can context-mode block dangerous tool calls in OpenClaw?

Yes. The `before_tool_call` hook runs a routing engine that can **deny**, **ask** for confirmation, or **modify** tool parameters before execution. Security rules can be defined in `hooks/core/routing.mjs` (OpenClaw-side) and supplemented by user-editable instructions in [`configs/openclaw/AGENTS.md`](https://github.com/mksglu/context-mode/blob/main/configs/openclaw/AGENTS.md) that get injected into the prompt.

### What is the session_key used for in the database?

The `session_key` provides a temporary identifier used during plugin initialization before OpenClaw assigns the permanent session ID. When the `session_start` hook fires, the plugin calls `renameSession()` in [`src/adapters/openclaw/session-db.ts`](https://github.com/mksglu/context-mode/blob/main/src/adapters/openclaw/session-db.ts) to migrate all temporary records to the final session ID, ensuring no events are lost during the startup sequence.

### Where is the session data stored when using OpenClaw?

Session data is stored in a SQLite database located at `~/.openclaw/context-mode/sessions/`. The database file is scoped per project using a SHA-256 hash of the project directory, ensuring isolation between different codebases while allowing shared access to the singleton database instance within the same OpenClaw process.