Tools

Canon Guardian

Name: Canon Guardian
Rating: 3.5 (1 reviews)
Author: smonett

By smonett 👁 53 views ▲ 0 votes

Canon Guardian — selective workspace canon re-injection plugin for OpenClaw. Solves the silent model fallback personality drift problem.

GitHub

Configuration Example

{
  "plugins": {
    "entries": {
      "canon-guardian": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

README

# Canon Guardian 🛡️

**Selective workspace canon re-injection for OpenClaw.**

Your AI agent has a personality file (`SOUL.md`), operating rules (`AGENTS.md`), and a whole identity loaded at session start. Then a model fails over, the fallback picks up the conversation, and suddenly your agent sounds like a stranger who found someone else's diary. Canon Guardian fixes that.

## The Problem

OpenClaw's `contextInjection: "continuation-skip"` is great for token cost — it skips re-injecting workspace bootstrap files on continuation turns. But it also means:

- **Model fallback** → fallback model inherits the transcript but not the personality
- **Manual model switch** (`/model`) → same problem
- **Long sessions** (6+ hours) → context drift, the agent slowly forgets who it is
- **Gateway restart** → next turn starts half-blind

The symptom is subtle: the session "feels different" but there's no alert, no seam, no signal. Just vibes going wrong.

## What This Does

A lightweight native plugin that re-injects your workspace canon at exactly the right moments:

| When | Why |
|---|---|
| First turn of a new session | Bootstrap the identity |
| Model switch (manual or fallback) | The new model needs the full briefing |
| 6+ hours since last injection | Drift defense |
| Every 50th turn | Periodic safety net |

On a quiet turn? One `Map` lookup, zero overhead. Re-injection fires on roughly **2–4% of turns** in practice.

## Why Not Just Use `contextInjection: "always"`?

You can! If your sessions are short or your canon is small, that's the simpler answer.

But if you're running a 50KB canon across 200-turn sessions on Opus rates, the difference between "every turn" and "2–4% of turns" is your coffee budget for the month.

## Install

```bash
clawhub install canon-guardian
```

Or manually: drop the plugin folder into `~/.openclaw/plugins/canon-guardian/` and add to your config:

```json
{
  "plugins": {
    "entries": {
      "canon-guardian": {
        "enabled": true,
        "config": {}
      }
    }
  }
}
```

## Configuration

All optional. Defaults are sensible.

```json
{
  "plugins": {
    "entries": {
      "canon-guardian": {
        "enabled": true,
        "config": {
          "canonFiles": ["AGENTS.md", "SOUL.md", "ROLE.md", "USER.md", "TOOLS.md", "MEMORY.md"],
          "injectionInterval": 50,
          "restartIdleMs": 21600000,
          "logInjections": true
        }
      }
    }
  }
}
```

| Setting | Default | What it does |
|---|---|---|
| `canonFiles` | Core workspace files | Which files to re-inject |
| `injectionInterval` | `50` | Re-inject every N turns as a safety net |
| `restartIdleMs` | `21600000` (6h) | Treat as restarted if idle longer than this |
| `logInjections` | `true` | Log each re-injection with reason |

## Multi-Model Support

Canon Guardian detects model switches by tracking `${providerId}:${modelId}` per session. Every provider transition triggers re-injection:

- Anthropic ↔ xAI/Grok ↔ Google/Gemini ↔ OpenAI
- Same provider, different tier (e.g. Opus → Haiku)
- Native fallback chain transitions

**Grok bonus:** When the active model is a Grok/xAI model, the plugin automatically appends `AGENTS-GROK.md` if it exists in your workspace — useful if you maintain model-specific operating notes.

## How It Works

Uses the `before_prompt_build` hook to return `prependSystemContext`, placing the canon in the **cache-eligible prefix** of the system prompt. Composes cleanly with other plugins (like `active-memory`) because OpenClaw concatenates `prependSystemContext` segments rather than overwriting.

We tried `llm_input` first. That was wrong — cost us a few bad turns before we figured it out. `before_prompt_build` is the maintainer-blessed hook for system prompt mutation.

## Requirements

- OpenClaw 2026.4.0+
- `contextInjection: "continuation-skip"` (the default these days)

If you're already on `contextInjection: "always"`, you don't need this plugin — you're paying for full re-injection every turn anyway.

## Backstory

Born from a real production incident: we run OpenClaw as a daily-driver AI assistant with a rich workspace canon (~50KB across 6 files). One day the primary model rate-limited, the fallback took over silently, and our agent went from "trusted engineering partner with dry humor" to "generic helpful assistant." No alert, no signal — just vibes going sideways.

We filed the underlying platform gap as [openclaw/openclaw#65824](https://github.com/openclaw/openclaw/issues/65824) (item 1) and built this plugin as a local mitigation. It's been running in production since April 2026 without issues.

**Source:** [github.com/smonett/canon-guardian](https://github.com/smonett/canon-guardian)

## License

MIT

tools