Voice
Token Saver
By OpenClaw plugin that spills oversized tool results into artifacts and recalls only the relevant summaries later.
Install
npm install
npmREADME
# Token Saver for OpenClaw
[English](./README.md) | [ä¸ć–‡](./README_zh.md)
OpenClaw already has strong caching and compaction, but noisy tool loops still waste context when `exec`, `read`, or `web_fetch` dump huge blobs into the transcript. Token Saver is built around two layers working together: RTK-backed exec rewriting for noisy shell reads, plus OpenClaw-native artifact spill and prompt-time recall for oversized results that still reach the transcript. The result is a public plugin that keeps RTK in the loop, preserves auditability, and lets follow-up turns recover only the parts that matter.
## Install in one line
```bash
openclaw plugins install --dangerously-force-unsafe-install token-saver --marketplace https://github.com/sypsyp97/openclaw-token-saver
```
This repository is also a remote OpenClaw marketplace, so the GitHub URL is enough. The dangerous-install flag is required because the plugin invokes the external `rtk` binary for exec rewriting.
## Scope of the public release
This public marketplace build includes the RTK-assisted exec rewrite path together with artifact spill and prompt recall.
- it includes RTK-aware exec rewriting in the shipped plugin code
- the default backend is `rtk-then-head`, so read-only exec calls try RTK first and fall back to a conservative head cap
- RTK itself is still installed separately on the host, which keeps the plugin small and the integration explicit
## Give this repo to your OpenClaw
Paste this to your OpenClaw and let it do the install for you:
```text
Install the token-saver plugin from https://github.com/sypsyp97/openclaw-token-saver using:
openclaw plugins install --dangerously-force-unsafe-install token-saver --marketplace https://github.com/sypsyp97/openclaw-token-saver
Then verify it with `openclaw plugins inspect token-saver`.
```
## What it does
### 1. Rewrite noisy exec reads with RTK first
- default backend is `rtk-then-head`
- targets obvious read-only exec commands first
- tries `rtk rewrite <command>` when RTK is available
- falls back to a conservative `head` cap for safe read-only commands
### 2. Spill oversized tool results into local artifacts
- targets `exec`, `read`, and `web_fetch`
- keeps small results inline
- stores oversized results as JSON artifacts on disk
- writes a searchable `index.jsonl`
- tracks savings in `stats.json`
### 3. Keep the transcript useful
Instead of dumping raw head and tail fragments, Token Saver writes a compact persisted preview with:
- artifact path
- summary text
- key lines
- partial-result warnings when a default `read` or `web_fetch` cap was auto-applied
### 4. Recall only what the next turn actually needs
On explicit follow-up requests like “show the error”, “give me the output”, or “open that file section”, the plugin searches same-session artifact metadata and injects a bounded recall block with the most relevant summaries.
## Installation modes
### Remote GitHub marketplace
```bash
openclaw plugins install --dangerously-force-unsafe-install token-saver --marketplace https://github.com/sypsyp97/openclaw-token-saver
```
### Local checkout
```bash
git clone https://github.com/sypsyp97/openclaw-token-saver.git
cd openclaw-token-saver
openclaw plugins install --dangerously-force-unsafe-install .
```
### RTK prerequisite
Install RTK on the host first if you want the default RTK-backed rewrite path to be active:
```bash
brew install rtk
# or: cargo install --git https://github.com/rtk-ai/rtk
```
## Recommended config
```json5
{
plugins: {
entries: {
"token-saver": {
enabled: true,
config: {
enabled: true,
defaultWebFetchChars: 12000,
execRewriteBackend: "rtk-then-head",
execRewriteScope: "readOnly",
execRewriteRtkBinary: "rtk",
execRewriteRtkTimeoutMs: 2000,
readOnlyExecMaxLines: 200,
maxInlineChars: 12000,
previewHeadChars: 1600,
previewTailChars: 600,
enablePromptRecall: true,
recallLimit: 3,
recallMinScore: 4,
maxStoredArtifacts: 200,
summaryLineBudget: 8,
maxRecallChars: 5000
}
}
}
}
}
```
### Optional conservative read defaults
If you want the plugin to auto-cap bare `read` calls, turn this on explicitly:
```json5
{
plugins: {
entries: {
"token-saver": {
config: {
autoLimitReadByDefault: true,
defaultReadLimit: 400
}
}
}
}
}
```
The safer default is to leave `autoLimitReadByDefault` off and rely on artifact spill plus explicit follow-up reads.
## Files managed by the plugin
Inside `artifactDir` relative to the plugin root, Token Saver manages:
- one JSON payload per oversized tool result
- `index.jsonl` for searchable artifact metadata
- `stats.json` for savings counters
## Why this design
This plugin is deliberately narrow even with RTK included.
- It does not bypass the OpenClaw context engine.
- It does not hide that a tool result was partial.
- It does not silently invent missing lines beyond a cap.
- It keeps RTK as an explicit external binary instead of burying a private rewrite layer inside the plugin.
- It does not auto-rehydrate huge blobs unless the follow-up request clearly asks for them.
That keeps the behavior legible, debuggable, and easy to remove.
## Develop locally
```bash
npm install
npm test
```
The test script runs:
- `node --check index.js`
- JSON manifest sanity checks
- `openclaw plugins marketplace list` smoke test when `openclaw` is available
- temp-home install + inspect smoke test when `openclaw` is available
- install verification with `--dangerously-force-unsafe-install`
## Repository layout
```text
.
├── index.js
├── marketplace.json
├── openclaw.plugin.json
├── package.json
└── scripts/test.sh
```
## Credits
- RTK integration and the command-rewrite approach build directly on [RTK](https://github.com/rtk-ai/rtk), the CLI proxy by the `rtk-ai` team.
- Token Saver adds the OpenClaw-side layer: artifact spill, transcript slimming, persisted summaries, and prompt-time recall.
- Public release credit should stay explicit whenever this plugin is described or repackaged.
## License
MIT
voice
Comments
Sign in to leave a comment