How to set-up efficient context cache in OpenClaw?

[swift sundial]

I want to use OpenClaw for coding a Discord bot using OpenRouter and Sonnet 4.6. I want to ensure cache works correctly, so for this context mustn't change, and I want to include the Discord.js docs in the cache. How do I do that?

[safe anchor]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[prisma raft]

Yep. The short version is:

1. Use a real OpenRouter Anthropic model ref
   Example: openrouter/anthropic/claude-sonnet-4-6

   Keep it pointed at OpenRouter itself. OpenClaw only adds the Anthropic cache markers for openrouter/anthropic/* when the route still resolves to openrouter.ai. If you repoint it to some random OpenAI-compatible proxy, that cache behavior stops.

2. Put stable context in bootstrap files, not chat history
   OpenClaw caches unchanged prompt prefixes. The stable prefix already includes injected workspace files like:
   AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md

3. Do not put full Discord.js docs in a skill and expect them to be preloaded
   Skills only inject metadata by default. The actual SKILL.md is read on demand.
   So if you want Discord.js material inside the cached prefix, use a bootstrap file instead.

Good setup

In openclaw.json (JSON5), something like:

{
  agents: {
    defaults: {
      model: {
        primary: "openrouter/anthropic/claude-sonnet-4-6"
      },
      models: {
        "openrouter/anthropic/claude-sonnet-4-6": {
          params: {
            cacheRetention: "long" // or "short"
          }
        }
      },

      contextPruning: {
        mode: "cache-ttl",
        ttl: "1h"
      },
      heartbeat: {
        every: "55m" // optional, useful if you want to keep a 1h cache warm
      }
    }
  },
  hooks: {
    internal: {
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: ["context-cache/discordjs/TOOLS.md"]

        }
      }
    }
  }
}

Then create a file in your workspace like:

context-cache/discordjs/TOOLS.md

and put a curated, stable Discord.js reference there, not the whole docs dump.

What to include in that file

Keep it static and high-value, for example:

• intents / partials you use
• slash command patterns
• interaction lifecycle rules
• buttons, modals, select menus
• embeds / attachments
• collectors
• permission checks
• common Discord.js gotchas
• your bot architecture conventions

What not to do

• Do not keep editing that file during the session
• Do not stuff the entire Discord.js docs in there
• Do not rely on SKILL.md for “always cached docs”

OpenClaw caps bootstrap injection at 12k chars per file and 60k total by default, so giant docs will get truncated anyway.

How to verify it’s working

1. Run /context detail

   • confirm your extra file is injected
   • confirm it is not truncated

2. Run a request, then check /status

   • first relevant turn should usually show cacheWrite
   • next similar turn, within TTL, should show cacheRead > 0

If cacheRead stays 0, common causes are:

• you changed AGENTS.md / extra bootstrap file
• you changed model/provider route
• you are no longer really hitting openrouter.ai
• cache TTL expired
• prompt shape changed too much