Tools

Keystone

Name: Keystone
Rating: 3.5 (1 reviews)
Author: joshuaswarren

By joshuaswarren 👁 110 views ▲ 0 votes

Structural stability plugin for OpenClaw. Reduces rule drift, context loss, tool amnesia, routing surprises, formatting failures, config mistakes, and delegation errors.

GitHub

Install

openclaw plugins install @joshuaswarren/openclaw-keystone

Configuration Example

{
  "plugins": {
    "allow": ["openclaw-keystone"],
    "entries": {
      "openclaw-keystone": {
        "enabled": true,
        "config": {
          "governanceEnabled": true,
          "docsFirstEnabled": true,
          "contextBudgetEnabled": true,
          "toolRegistryEnabled": true,
          "toolRegistryInjectionMode": "summary",
          "configGuardEnabled": true,
          "delegationQualityEnabled": true,
          "routingCostEnabled": true,
          "formattingEnabled": true,
          "errorSanitizerEnabled": true
        }
      }
    }
  }
}

README

# openclaw-keystone

**Structural stability for OpenClaw agents.** Keystone is an OpenClaw plugin that reduces recurring operator failure modes before they become daily support work: rule drift, docs-skipping, context blowouts, compaction loss, tool amnesia, routing surprises, formatting failures, unsafe config edits, vague delegation, and raw error dumps.

[![npm version](https://img.shields.io/npm/v/@joshuaswarren/openclaw-keystone)](https://www.npmjs.com/package/@joshuaswarren/openclaw-keystone)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Why Keystone?

OpenClaw can already do sophisticated work. The failure mode is not capability. It is execution drift.

Keystone adds lightweight guardrails around the points where agent systems most often fail:

- **Rule and docs injection** to keep the agent anchored in local operator instructions.
- **Context budget guardrails** to reduce whole-repo reads and context blowouts.
- **Compaction recovery** so active tasks and recent decisions survive context resets.
- **Tool reminders** to reduce tool amnesia and repeated reinvention.
- **Routing and cost audits** for lightweight operational runs.
- **Chat-friendly output shaping** for Telegram and other mobile-heavy channels.
- **Config write protection** against dangerous self-edits.
- **Delegation gates** for underspecified `sessions_spawn` tasks.
- **Error sanitization** so raw traces stay out of user-facing chat.

## What It Covers

Keystone targets the runtime failure patterns from the OpenClaw consultant DOD:

| Failure Pattern | Keystone Coverage |
|---|---|
| Rule exists, didn’t follow | Rule injection from local docs |
| Context loss after compaction | Compaction snapshot + recovery injection |
| Gateway crashes from config changes | Gateway config write guard |
| Delegation quality failures | `sessions_spawn` prompt gate |
| Tool amnesia | `TOOLS.md` reminder injection |
| Model routing and cost blowouts | Lightweight lane override + model usage audit |
| Formatting and presentation | Outbound message formatting guard |
| Raw errors relayed | Error sanitizer |
| Context blowout | Context budget guard |
| Guessing instead of reading docs | Docs-first injection |

## Quick Start

```bash
openclaw plugins install @joshuaswarren/openclaw-keystone --pin
```

Add Keystone to `openclaw.json`:

```jsonc
{
  "plugins": {
    "allow": ["openclaw-keystone"],
    "entries": {
      "openclaw-keystone": {
        "enabled": true,
        "config": {
          "governanceEnabled": true,
          "docsFirstEnabled": true,
          "contextBudgetEnabled": true,
          "toolRegistryEnabled": true,
          "toolRegistryInjectionMode": "summary",
          "configGuardEnabled": true,
          "delegationQualityEnabled": true,
          "routingCostEnabled": true,
          "formattingEnabled": true,
          "errorSanitizerEnabled": true
        }
      }
    }
  }
}
```

Then restart the gateway in a planned maintenance window.

## Verify Installation

```bash
npm ci
npm run check-types
npm test
npm run build
```

For a packaged smoke test:

```bash
npm pack --dry-run
```

## How It Works

Keystone works by attaching to existing OpenClaw plugin hooks. It does not require any core OpenClaw patches.

| Hook | Purpose |
|---|---|
| `before_model_resolve` | Lightweight model override for cheap operational runs |
| `before_prompt_build` | Rules, docs-first, context-budget, and tool reminders |
| `before_agent_start` | Post-compaction recovery injection |
| `before_tool_call` | `sessions_spawn` quality gate and gateway config write guard |
| `message_sending` | Telegram/mobile formatting cleanup |
| `tool_result_persist` | Raw error sanitization before transcript persistence |
| `llm_output` | Provider/model usage audit logging |
| `before_compaction` / `after_compaction` | Snapshot capture and post-compaction tracking |

## Configuration

All settings live under `plugins.entries.openclaw-keystone.config`.

Core defaults are privacy-safe:

- remote tool indexing is off by default
- raw error persistence is off by default
- tool summaries are omitted from compaction snapshots by default
- routing overrides do nothing until you choose a preferred provider/model

See:

- [docs/config-reference.md](docs/config-reference.md)
- [docs/getting-started.md](docs/getting-started.md)
- [docs/architecture/overview.md](docs/architecture/overview.md)

## Development

Clone and build:

```bash
git clone https://github.com/joshuaswarren/openclaw-keystone.git
cd openclaw-keystone
npm ci
npm run build
```

Run the maintainer checks:

```bash
npm run preflight
```

Install local Git hooks:

```bash
npm run hooks:install
```

## Contributing

Start with [CONTRIBUTING.md](CONTRIBUTING.md). Important rules:

- keep changes small and focused
- add tests for behavior changes
- update docs for public/config changes
- update [CHANGELOG.md](CHANGELOG.md) for user-facing changes
- do not commit secrets or install-specific data

Issue and PR templates are included under `.github/`.

## Security

Report vulnerabilities privately through GitHub Security Advisories:

- https://github.com/joshuaswarren/openclaw-keystone/security/advisories/new

See [SECURITY.md](SECURITY.md) for scope and disclosure expectations.

## Documentation Index

- [docs/README.md](docs/README.md)
- [docs/getting-started.md](docs/getting-started.md)
- [docs/config-reference.md](docs/config-reference.md)
- [docs/architecture/overview.md](docs/architecture/overview.md)
- [docs/ops/pr-review-hardening-playbook.md](docs/ops/pr-review-hardening-playbook.md)
- [docs/ops/release-process.md](docs/ops/release-process.md)

## License

[MIT](LICENSE)

tools