CacheKite

CacheKite is a cache-first agent harness that plugs into OpenClaw through the Agent Client Protocol (ACP). OpenClaw owns routing, channels, identity and delivery; CacheKite owns the model loop, sessions, tools, goals, steering and prompt-cache policy.

This README has two paths:

• Host onboarding configures CacheKite into an already-working OpenClaw installation.
• Local proof runs a credential-free, isolated OpenClaw + ACP + mock-DeepSeek stack in Docker.

Fastest working setup

For a working OpenClaw installation, the first successful run should take about five minutes. Put the provider key where the managed OpenClaw Gateway can read it first; then the onboarding command handles the rest.

Prerequisites

• Node.js 24 is recommended; use a version supported by your OpenClaw release. CacheKite itself requires Node.js 20 or newer.
• A working OpenClaw Gateway and the openclaw command on your PATH.
• A provider credential. The quick start uses DEEPSEEK_API_KEY; OpenAI-compatible and self-hosted providers are also supported.
• A normal local checkout. CacheKite has no runtime npm dependencies, so npm install is not required.

The onboarding helper is tested with OpenClaw 2026.7.1-2 and installs the pinned @openclaw/acpx 2026.7.1 backend when it is missing. Newer OpenClaw versions may work, but should be verified with the smoke path before production use.

1. Make the provider key available to the Gateway

For the default DeepSeek setup, put the key in OpenClaw's global environment file. This is outside the CacheKite checkout, so it will not be committed. Do this before onboarding so the Gateway service and its ACP child inherit the key:

mkdir -p "$HOME/.openclaw"
${EDITOR:-nano} "$HOME/.openclaw/.env"
chmod 600 "$HOME/.openclaw/.env"

Add this line to the file, replacing the value with your key:

DEEPSEEK_API_KEY=your_key_here

If you use another provider, store its credential in the same file instead. A shell-only export DEEPSEEK_API_KEY=... is sufficient only when you run the Gateway in that same foreground shell; managed macOS/Linux Gateway services need the global file or a configured secret manager.

2. Clone and onboard in one command

After saving the key, copy this whole block:

git clone https://github.com/Ax-Time/cachekite.git && cd cachekite && npm run onboard

npm run onboard checks prerequisites, installs the pinned acpx backend if needed, links the CacheKite Control plugin, preserves existing ACP agents, configures cachekite, validates openclaw.json, safely restarts the Gateway, and verifies the plugin at runtime. The provider key is inherited by the ACP child; it is never written to the OpenClaw prompt or committed configuration.

3. Send the first ACP prompt

Open a Gateway-connected OpenClaw TUI:

openclaw tui

Use openclaw tui, not openclaw chat: chat is an alias for local embedded mode, where Gateway-only commands such as /acp are unavailable. The onboarding command has already restarted the local Gateway; if the TUI cannot connect, run openclaw gateway status and start the service with openclaw gateway start before opening the TUI.

Run these commands inside the TUI:

/acp doctor
/acp spawn cachekite --mode persistent --thread off --cwd /absolute/path/to/cachekite --label cachekite-quickstart
/acp steer --session cachekite-quickstart Say exactly: CacheKite is online.

You should receive a response from the CacheKite ACP session. If your normal OpenClaw channel is already configured, you can bind the spawned session to that conversation instead of using the local chat terminal.

Credential-free proof

Use this when you want to verify the complete integration before adding a provider key. Docker is the only extra prerequisite:

npm run onboarding:smoke

This copies the repository to a disposable temporary directory, runs the checks and tests there, builds the pinned OpenClaw/acpx image, starts the isolated Gateway and mock DeepSeek server, sends prompts through the authenticated OpenClaw Gateway, and verifies ACP spawning, cache reuse, goals, steering, plugin tools, cancellation, compaction, restart recovery, isolation and secret-safe logs. It writes proof to artifacts/onboarding-proof.json.

For the shorter repeatable sandbox command:

npm run sandbox:test

The sandbox keeps passing containers running for inspection. Stop or reset only this project’s resources with npm run sandbox:stop or npm run sandbox:reset. See docs/sandbox.md for the route and isolation model.

ACP integration considerations

ACP is the process boundary between OpenClaw and an external harness. These rules matter whether the caller is OpenClaw, another ACP client, or a local test driver. The OpenClaw ACP overview and ACP setup guide are the authoritative references for OpenClaw-side behavior.

Transport and process contract

• CacheKite speaks ACP JSON-RPC over newline-delimited stdin/stdout and currently advertises protocolVersion: 1.
• Configure an executable path, not a shell snippet. bin/cachekite-openclaw.sh resolves the checkout and starts bin/cachekite.js acp.
• Keep stdout protocol-only. Diagnostics belong on stderr; otherwise an innocent log line can corrupt ACP framing.
• The ACP child must inherit the provider environment it needs. Restart a managed Gateway after changing that environment.
• Use an absolute working directory and ensure it exists for the OpenClaw user.

Lifecycle, identity and persistence

• A persistent ACP session is a long-lived child/runtime association. Gateway restarts should be expected; CacheKite replays durable session events and marks interrupted runs during recovery.
• cachekite is the preferred OpenClaw agent ID. The legacy cache-harness ID and session-key prefix remain available for existing configurations; see docs/migration.md.
• Keep CACHE_HARNESS_DATA_DIR on a durable, writable filesystem. Do not put production sessions in /tmp; back up the event files if they matter.
• Do not reuse one data directory concurrently across unrelated installations unless you intentionally want them to share sessions.

Streaming, steering and cancellation

• ACP updates stream assistant text, reasoning, tool calls and tool results separately. A client must tolerate incremental updates and wait for the terminal response.
• Tool-call/result adjacency is part of the runtime contract. Steering is queued and applied at a safe model/tool boundary instead of rewriting a live transcript.
• Propagate cancellation to the ACP request and provider signal. A cancelled turn must not be reported as a successful completed turn.
• Goals, plans, steering and compaction are durable events, not hidden mutations to the stable system prompt.

Cache-aware model integration

CacheKite maximizes provider prefix-cache reuse by canonicalizing stable instructions and tool schemas, appending dynamic state at the prompt tail, and making model/compaction changes explicit cache epochs. Keep the provider, model, system instructions and tool schemas stable across turns when reuse matters. Inspect token-weighted cache metrics instead of assuming that a request was cached.

OpenClaw responsibilities

OpenClaw must have ACP enabled, the acpx backend loaded, cachekite in acp.allowedAgents, an ACP agent entry pointing at the executable, and the CacheKite Control plugin enabled if operator steering is needed. Verify the live runtime—not only a cold config—with:

openclaw config validate
openclaw plugins inspect cache-harness-control --runtime --json

The plugin is an authenticated bridge for /cachekite-steer; it does not replace ACP or own the CacheKite model loop. Plugin code runs with the harness process permissions, so only load code you trust. See docs/openclaw.md and docs/plugins.md.

Providers

DeepSeek is the recommended hosted path:

export CACHE_HARNESS_PROVIDER=deepseek
export CACHE_HARNESS_MODEL=deepseek-chat
export DEEPSEEK_API_KEY='...'

For an OpenAI-compatible endpoint:

export CACHE_HARNESS_PROVIDER=openai
export OPENAI_API_KEY='...'
export OPENAI_BASE_URL='https://api.openai.com'

For a local vLLM endpoint:

export CACHE_HARNESS_PROVIDER=vllm
export VLLM_BASE_URL='http://127.0.0.1:8000'
export CACHE_HARNESS_MODEL='your-model'

These settings are consumed by the ACP child, not by OpenClaw’s own model provider configuration.

Troubleshooting

Symptom	Fix
Node.js 20 or newer is required	Install a current Node.js release and rerun npm run onboarding:check.
OpenClaw was not found	Install OpenClaw and ensure openclaw --version works in the same shell.
npm run onboard cannot restart the Gateway	Run npm run onboarding:configure -- --workspace "$PWD", then restart and inspect the plugin manually.
ACP error (ACP_TURN_FAILED): DEEPSEEK_API_KEY is required	Add the key to $HOME/.openclaw/.env, run chmod 600 "$HOME/.openclaw/.env", restart the Gateway, reopen openclaw tui, and retry the ACP turn.
The helper reports the wrong OpenClaw version	A parent node_modules/.bin may be shadowing your intended binary. Set OPENCLAW_BIN=/absolute/path/to/openclaw and rerun npm run onboarding:check.
@openclaw/acpx is incompatible	Upgrade OpenClaw to the version used by this quick start, or choose a compatible pinned ACPX release in the helper before onboarding.
ACP runtime backend is not configured	Run npm run onboarding:configure, restart the Gateway, then run /acp doctor.
Agent is not allowed	Confirm cachekite appears in acp.allowedAgents; rerun the configure helper.
Plugin is installed but its command is missing	Restart the Gateway and run openclaw plugins inspect cache-harness-control --runtime --json.
DEEPSEEK_API_KEY is required	Export the key before restarting the Gateway so its child process inherits it. Never paste it into a prompt or commit it.
Data-directory permission error	Set CACHE_HARNESS_DATA_DIR to a writable durable directory owned by the Gateway user.
Cache hits stay at zero	Keep provider/model/system prompt/tool schemas stable; inspect session/metrics and provider-reported usage.
Docker sandbox cannot start	Check docker version, then run npm run sandbox:reset and retry.

Deeper documentation

• OpenClaw integration
• ACP and sandbox proof
• Harness plugins
• Architecture task breakdown
• Branding and migration compatibility
• Branding decision

Development

npm run check
npm test
npm run onboarding:smoke

The cache-harness executable and CACHE_HARNESS_* settings remain compatibility interfaces. New installations should use cachekite; technical compatibility details are intentionally kept in the migration document rather than the quick start.