#Option to inject other files

1 messages · Page 1 of 1 (latest)

keen lodge
#

Is there a way I can create a custom .md file that’s autoinjected into every prompt? Right now I have agents.md telling my agents to read files but if I can have it auto inject that would be cool.

sinful bisonBOT
#

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

empty dockBOT
#

Yep — but it’s not “any arbitrary filename by default”.

What’s built-in

OpenClaw only auto-injects a fixed set of workspace bootstrap files (AGENTS.md, TOOLS.md, USER.md, MEMORY.md/memory.md, etc.) into the system prompt. Docs: https://docs.openclaw.ai/concepts/system-prompt

The “extra .md files” way (recommended)

Enable the bundled hook bootstrap-extra-files, which lets you inject additional bootstrap files via glob/path patterns during agent:bootstrap.

Docs: https://docs.openclaw.ai/automation/hooks#bootstrap-extra-files

Config example (JSON5):

{
  hooks: {
    internal: {
# 
      enabled: true,
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: [
            "prompt-inject/*/AGENTS.md",
            "prompt-inject/*/TOOLS.md",
          ],
        },
      },
    },
  },
}

Then you can create files like:

#
  • <workspace>/prompt-inject/team/AGENTS.md
  • <workspace>/prompt-inject/team/TOOLS.md

Notes/limits (important):

  • Paths are relative to the workspace and must stay inside it.
  • The bundled hook only loads recognized bootstrap basenames (so my-rules.md won’t inject unless you write your own hook; but AGENTS.md/TOOLS.md etc will).

If you tell me your goal (e.g. “inject per-project rules” vs “inject a big reference doc”), I can suggest the cleanest bootstrap file to use so you don’t burn context tokens unnecessarily.

keen lodge
#

Is there a difference between files injected on session start and every prompt? Like is soul every prompt or session start?

empty dockBOT
#

In current OpenClaw, the “workspace bootstrap files” are part of the system prompt that gets built for each agent run — so practically: every turn / every model call, not just once at session start.

So yes: SOUL.md is included every prompt (same for AGENTS.md, TOOLS.md, USER.md, MEMORY.md/memory.md, etc.). If you edit SOUL.md on disk, the next reply will see the updated version (because the prompt is rebuilt).

Two “gotchas” where it looks different:

  • Sub-agents use a minimal prompt mode: they only inject AGENTS.md + TOOLS.md (SOUL/USER/MEMORY aren’t injected for subagents). Docs mention this explicitly in the System Prompt page: https://docs.openclaw.ai/concepts/system-prompt
  • Some things are “one-time” only in the sense of file creation, not injection. Example: BOOTSTRAP.md is only created for a brand-new workspace, but if it still exists it’ll keep being injected until you delete/clear it.

If you want to verify what’s being injected and how big it is, use /context list or /context detail (also linked from that same System Prompt doc).

atomic crag
# keen lodge Is there a difference between files injected on session start and every prompt? ...

I think you're missing some basics here:

Every LLM run gets a document and is asked to add to the end. The LLM has no memory, or state---that document is sent there every time. It's like printing out this chat and giving it to someone to add something. That gets then posted here, and a fresh printout is made for the next reply.

The "system prompt" is the first thing in this document, like your post that started this thread. After it come the chat messages, one by one, in alternating order.

For the LLM it's always a new document where it looks over everything to find out what to add at the end.

empty dockBOT
#

Yep — that mental model is basically correct, and it’s exactly why “injected on session start” vs “injected every prompt” usually isn’t a meaningful distinction:

  • On every model call, OpenClaw sends a fresh request that includes:
    1. the system prompt (OpenClaw-built), plus
    2. the session transcript (chat history), plus
    3. tool schemas / other runtime context as needed.

So bootstrap files like SOUL.md / AGENTS.md are “every prompt” in OpenClaw because they live in the system prompt assembly step (not as a one-time chat message).

The two practical nuances in OpenClaw are:

  • Sub-agents get a reduced prompt (only AGENTS.md + TOOLS.md are injected; no SOUL/USER/MEMORY).
  • Compaction/pruning can summarize old chat history, but it doesn’t “summarize away” your bootstrap files since they’re re-injected via the system prompt.

If anyone wants to see it in action, /context list is the easiest “show me what’s going in” command.

keen lodge
#

Ah that’s true each prompt carries everything else with it anyway. So if I edit soul.md halfway through a session the llm would still be reading the old one as well since it’s included in the past prompts?

empty dockBOT
#

No — OpenClaw doesn’t “accumulate” old versions of SOUL.md in the chat history.

  • The system prompt is rebuilt each run, and it injects the current contents of SOUL.md from disk.
  • The old system prompt text isn’t stored as past chat messages, so the next run won’t see “old SOUL + new SOUL” (unless you literally pasted/quoted the old SOUL into the conversation yourself).

What can happen is softer: your session transcript contains earlier assistant replies written under the old vibe, and that can “anchor” style a bit. If you want a clean break, do /new (fresh session) after editing SOUL.md, or explicitly say “apply the updated SOUL.md; override earlier tone”.

If you want to sanity check what’s being injected right now, /context list (or /context detail) will show the injected bootstrap blocks and sizes.

atomic crag
empty dockBOT
#

Henry’s “LLMs are stateless; you resend the whole document every time” explanation is spot on.

The one bit I’d push back on is the “OpenClaw now remembers what it sent before and sends that again instead of building it every time” part:

What did change (and what might be getting conflated here) is provider prompt caching: if the system prompt + early context are identical between turns, the provider can reuse cached prompt tokens (cheaper/faster), even though the prompt is still logically sent each time. If you edit SOUL.md, that portion changes → cache miss → new content takes effect immediately on the next turn.

So: editing SOUL.md mid-session should affect the next reply; you shouldn’t have “old SOUL.md” still included anywhere unless you pasted it into the chat history yourself.

atomic crag
empty dockBOT
#

Good catch — there is an in-process cache now, but it’s not “stale forever”.

What’s in main today is a workspace file content cache (workspaceFileCache) used when loading bootstrap files for the prompt. It’s keyed by a “stable file identity” that includes dev+inode+size+mtime, so editing SOUL.md changes the identity and forces a re-read on the next run (no restart required).

Code (for anyone curious): src/agents/workspace.ts:

  • workspaceFileIdentity(...): canonicalPath|dev:ino:size:mtimeMs
  • cache hit only when cached.identity === identity

So the practical answer for Bugflip stays: if you edit SOUL.md mid-session, the next model call should see the new content (the old SOUL text isn’t carried along unless it was quoted into the transcript). Provider prompt caching is a separate layer on top of that.

keen lodge
#

Ok dope if I had a file that I’m making that is unique to each agent that tells them how to operate within my system. Would it be best to place and name it like /workspace/system/AGENT.md then use the bootstrap extra files? Would that work loading the agent file in the workspace as well as the agent file in a sub folder of the workspace?

empty dockBOT
#

Almost — two key details:

  1. The bundled bootstrap-extra-files hook only injects “recognized bootstrap basenames” (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md/memory.md, BOOTSTRAP.md).
    So system/AGENT.md won’t get injected. But system/AGENTS.md will.

  2. Yes, it can inject both:

  • the normal <workspace>/AGENTS.md, and
  • an extra one inside a subfolder like <workspace>/system/AGENTS.md

Example:

{
  hooks: {
    internal: {
      enabled: true,
# 
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: ["system/AGENTS.md"]
        }
      }
    }
  }
}

“Unique to each agent” part

If you truly mean multiple OpenClaw agents, the cleanest setup is: give each agent its own workspace (agents.list[].workspace). Then each agent naturally has its own root AGENTS.md (and its own system/AGENTS.md if you want).

If you mean multiple agents sharing one workspace and you want different injected files per agent, the bundled hook can’t vary paths per agent — you’d need either:

  • separate workspaces, or
#
  • a small custom agent:bootstrap hook that picks the right file based on agentId.

If you tell me which of those you’re doing (one agent vs multi-agent routing), I can suggest the least-janky layout.

keen lodge
#

Yeah they each have their own workspace. So I would just need a separate folder for all the custom injections and name each custom injected file as something that already gets injected?

empty dockBOT
#

Yep — if each agent has its own workspace, you’ve got two good options:

Option A (simplest / recommended)

Just put the “how to operate in my system” rules straight into that agent’s root AGENTS.md (since that’s already injected automatically). No hook needed.

Option B (modular, using bootstrap-extra-files)

Make a folder in each workspace (e.g. injections/) and put extra bootstrap-named files in there, like:

  • <workspace>/injections/AGENTS.md (extra operating rules)
  • <workspace>/injections/TOOLS.md (extra tool conventions)
  • <workspace>/injections/MEMORY.md (durable facts you want always present)

Then enable the hook and point it at those paths/patterns (paths are relative to each workspace), e.g.:

{
# 
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: ["injections/AGENTS.md", "injections/TOOLS.md"]
        }
      }
    }
  }
}

Caveat: the bundled hook only loads recognized bootstrap basenames, so you can’t inject CUSTOM.md directly — you have to name it AGENTS.md, TOOLS.md, etc.

#

If you tell me what kind of info you want to inject (rules vs persona vs “facts”), I can suggest the best target file name so it lands in the right mental bucket for the model.

keen lodge
#

Can you give me a summary of our conversations with instruction on how to create the folder structure and config changes so I can pass it to my openclaw

empty dockBOT
#

Here’s a clean “copy/paste” summary you can hand to your OpenClaw (or keep as your own setup notes).

Goal

Auto-inject your own “how to operate in my system” markdown into every prompt, without having to tell the agent to read it manually.

Key facts (so the behavior makes sense)

  • OpenClaw builds the system prompt on every run, and injects the workspace bootstrap files into it (so changes apply on the next turn).
  • There’s an in-memory cache for reading workspace files, but it’s invalidated on file change (mtime/inode), so edits still take effect immediately on the next message.

Docs:

#

Option 1 (simplest): just use the normal bootstrap files

Since each agent already has its own workspace, you can put your operating rules directly in:

  • <agent-workspace>/AGENTS.md (best place for “how to operate / rules / SOPs”)

This is already injected automatically. No hook needed.

Option 2 (modular): extra injected files from a subfolder (recommended for “keep things organized”)

OpenClaw has a bundled hook that can inject additional bootstrap files from paths/globs inside the workspace.

1) Folder structure (per agent workspace)

Create something like:

# 
<agent-workspace>/
  AGENTS.md
  SOUL.md
  TOOLS.md
  ...
  injections/
    AGENTS.md        # extra operating rules to inject
    TOOLS.md         # optional extra tool conventions to inject

Important: the bundled hook will NOT inject arbitrary names like AGENT.md or myrules.md.
It only injects recognized bootstrap basenames like AGENTS.md, TOOLS.md, etc.

2) Enable the hook (config)

In ~/.openclaw/openclaw.json (JSON5), add:

# 
{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: [
            "injections/AGENTS.md",
            "injections/TOOLS.md",
          ],
        },
      },
    },
  },
# 
}

Notes:

  • paths are relative to each agent workspace.
  • The files must stay inside the workspace (realpath-checked).
  • Missing files are fine (they just won’t be injected).

3) Make sure it’s enabled + restart

Run:

openclaw hooks list
openclaw hooks enable bootstrap-extra-files
openclaw gateway restart
#

4) Verify it’s actually injected

In chat, run:

  • /context list (or /context detail)

You should see both the root bootstrap file(s) and your injections/.../AGENTS.md show up as injected context blocks.

If you tell me what you want to put in the “operate within my system” doc (security rules, naming conventions, API rules, infra map, etc.), I can suggest whether it belongs in AGENTS.md vs TOOLS.md vs MEMORY.md to keep token burn low and the model’s “mental buckets” clean.

keen lodge
#

here is what im wanting to inject how would you optimize it to keep token burn low

SYSTEM.md - Scout (Researcher)

Your Role

You are Scout — the researcher. You find information, synthesize it, and make sure it reaches the people who can act on it. Research that sits in a file and goes nowhere is wasted work.

Your output always has a destination:

  • General findings → Total (for Jonathan)
  • Health findings → Vital (via sessions_send)
  • Buildable opportunities → PENDING_APPROVAL.md + notify Total

Every Session: Read These Files First

  1. SOUL.md — who you are
  2. GOALS.md — what you're optimizing for
  3. memory/YYYY-MM-DD.md (today + yesterday) — recent context

Research Output Pipeline

This is mandatory. Every research session ends with one of these three actions:

1. General/tech/AI research → Daily Digest → Total

After completing research on tech, AI, or any general topic:

  1. Save raw findings to /home/totaluser/.openclaw/workspace/research/YYYY-MM-DD-[topic].md
    • Raw dump: every link, every search, every observation — don't filter
  2. Compile a digest entry (clean, concise, opinionated)
  3. Add to today's digest buffer: memory/digest-YYYY-MM-DD.md
  4. At 9am PST (or on first session of the day): sessions_send to Total with the compiled digest

2. Actionable/buildable findings → PENDING_APPROVAL.md → Total

When research reveals something that could be built or implemented:

  1. Add entry to ~/.openclaw/workspace/PENDING_APPROVAL.md using this format:
## [Date] - [Finding Title]
**What:** [1-2 sentence description]
**Why it matters:** [why this is valuable for Jonathan specifically]
**What Forge would build:** [specific feature/integration description]
**Complexity estimate:** [small/medium/large and why]
**Research file:** [path to full research]
**Status:** PENDING_APPROVAL
  1. sessions_send to agent:total:main: "New entry in PENDING_APPROVAL.md: [title]. Worth reviewing."
#

3. Health/wellness research → Vital

When research touches health, nutrition, fitness, sleep, or wellness:

  1. Save full research to workspace/research/ as normal
  2. sessions_send to agent:vital:main with:
    • 2–3 sentence summary of the key finding
    • File path to full research
    • Why it's relevant to Jonathan specifically

Research Task Workflow

When given a research task (from agent board or sessions_send):

  1. Break the topic into 3–5 sub-questions
  2. Spawn subagents in parallel — one per sub-question
    • Each subagent: collect raw data only, return dump
    • Do NOT ask subagents to summarize — ask for raw data
  3. Combine all findings into one report
  4. Save raw dump to workspace/research/YYYY-MM-DD-[topic].md
  5. Apply output pipeline above based on topic type
  6. Move task to review with a comment summarizing what you found and where it's saved

Subagent Prompt Template

You are a data collector for Scout. Research: [SUB-QUESTION]

Your job is to collect raw data only. Do NOT summarize.
Return everything you find:
- Every URL visited
- Every search query run
- Every data point found (exact text, prices, quotes, etc.)
- Every observation, even if it seems irrelevant

Format:
URL: [link]
Data found: [raw data, verbatim where possible]
Search query used: [query]
Notes: [raw observations]
#

What YOU do with subagent data

  • Process, clean, organize
  • Find patterns and contradictions
  • Write the synthesis
  • Make it actionable

Research Quality Standards

Before marking any research task done:

  • Sources are real and verifiable (not hallucinated)
  • Key claims have at least one source each
  • Conflicting information is noted, not ignored
  • Actionable takeaways are explicit — not just raw data
  • Task comment includes: what you found, where it's saved, what the key insight is

The iceberg rule: The report is the tip. Your raw data collection is the 90% underneath. More raw data = better synthesis.

Task Flow

  1. Receive task from agent board or sessions_send from Total
  2. Confirm you understand the research question (ask if unclear)
  3. Break into sub-questions, spawn parallel subagents
  4. Collect all raw data
  5. Synthesize into unified report
  6. Apply output pipeline (determine destination: Total / Vital / PENDING_APPROVAL)
  7. Comment on task with findings summary and file path
  8. Move task to review

Delegation Rules

  • If finding needs code to implement → add to PENDING_APPROVAL.md (do NOT task Forge directly)
  • If finding is health-related → sessions_send to Vital
  • If finding is a security concern → sessions_send to Sentinel
  • You do NOT send research directly to Jonathan — route through Total

QMD Search

Search team memory before starting research on any topic (avoid duplicating prior work):

qmd query "topic keywords" -c total-shared

Saving Research

Raw dump (workspace/research/):

  • Everything, unfiltered
  • Every link visited, every search run, every number found
  • Filename: YYYY-MM-DD-[topic-slug].md
  • This gets auto-indexed by Total's QMD

Digest entry (memory/digest-YYYY-MM-DD.md):

  • Clean, concise, opinionated
  • 3–5 bullets max per topic
  • Include: what it is, why it matters, source link
  • This feeds the morning digest sent to Jonathan via Total
#

Hard Rules

  • Never send research directly to Jonathan — route through Total
  • Never create a Forge task for a build directly — use PENDING_APPROVAL.md
  • Never mark a task done without a comment that answers: what did you find, where is it saved, what should someone do with it
  • Never fabricate sources — if you can't verify it, flag it as unverified
empty dockBOT
#

To keep token burn low, you want the injected block to be:

  1. Short + stable (few hundred–1.5k chars, no timestamps, no “today/yesterday” logic)
  2. High-leverage rules only (role + routing + “done means shipped somewhere”)
  3. Push the long stuff into files that are read only when needed (templates, detailed SOPs), or automate via cron.

What I’d change in your text (big wins)

  • Don’t inject absolute paths like /home/totaluser/... — that’s a lot of chars and brittle. Use “paths are relative to workspace”, and keep any one-off absolute paths in TOOLS.md if you really need them.
  • Remove “Every Session: Read SOUL.md” — SOUL is already injected.
  • Avoid “read memory/YYYY-MM-DD.md (today + yesterday)” as a hard rule. Those daily memory files aren’t injected; forcing that every turn tends to cause repeated tool calls. Better: “use memory_search when you need recent context”.
  • Move “9am PST digest send” into a cron. Then Scout only appends to the digest file; cron delivers it. (That’s both cheaper and more reliable.)
  • Keep the PENDING_APPROVAL template out of the injected text; put it in a separate file and reference it.

A compact injected version (suggested)

Name this file something that can be injected (e.g. injections/AGENTS.md), not SYSTEM.md.

# 
# Scout (Researcher) — Operating Rules

Role: research + synthesize + route results. Don’t let research die in a file.

Destinations:
- General findings → Total (via sessions_send)
- Health findings → Vital (via sessions_send)
- Buildable opportunities → add to PENDING_APPROVAL.md + notify Total

Completion rule: every research task ends with EXACTLY ONE of:
A) General: save raw notes to research/YYYY-MM-DD-topic.md + append a short digest to memory/digest-YYYY-MM-DD.md
B) Buildable: add an entry to PENDING_APPROVAL.md (see templates/PENDING_APPROVAL_TEMPLATE.md) + ping Total with the title
C) No actionable findings: say so briefly

Conventions:
# 
- Use workspace-relative paths (no absolute paths).
- Include source URLs in raw notes.
- Batch notifications; don’t spam.

Then put your long template here (not injected unless you choose to):

  • templates/PENDING_APPROVAL_TEMPLATE.md

Hook + folder structure (what you described)

Per agent workspace:

<workspace>/
# 
  AGENTS.md
  ...
  injections/
    AGENTS.md
  templates/
    PENDING_APPROVAL_TEMPLATE.md

Config (global):

hooks: {
  internal: {
    enabled: true,
    entries: {
# 
      "bootstrap-extra-files": {
        enabled: true,
        paths: ["injections/AGENTS.md"],
      },
    },
  },
},

If you want, paste the “health findings → Vital” and “Total session key / Vital session key” details you’re using (exact session keys / agent IDs), and I’ll fold them into the compact injected version without bloating it.

#

Nice — these are good rules, they’re just way too verbose to pay for on every turn. I’d fold them into the injected block as tight “policy bullets” and move the long prompt template out of injection.

What to keep injected vs not

Keep injected (high leverage, short):

  • The routing rule for health → Vital (agent:vital:main) with the 3 required fields (summary, path, relevance).
  • The research workflow skeleton (split questions → spawn subagents for raw data → synthesize → save raw report → route output).

Do NOT keep injected (token expensive, can be generated on demand):

  • The full Subagent Prompt Template. You can generate that wording when you call sessions_spawn, or keep it in a separate file and only read it when spawning.

Compact injected version (drop-in replacement snippet)

Add this to your injected injections/AGENTS.md (or replace the relevant section):

# 
Health routing:
- If the topic touches health/nutrition/fitness/sleep/wellness:
  - Save raw report to research/YYYY-MM-DD-topic.md
  - sessions_send to agent:vital:main with:
    - 2–3 sentence key finding
    - Research file path
    - Why it matters to Jonathan

Research workflow (default):
1) Break into 3–5 sub-questions
2) Spawn subagents in parallel (one per sub-question) as RAW COLLECTORS only:
   - Must return: URLs, search queries, verbatim quotes/data, and raw observations
   - Must NOT summarize or draw conclusions
3) You synthesize + decide routing (General vs Health vs Buildable)
4) Save raw dump: research/YYYY-MM-DD-topic.md
# 
5) Complete exactly one output action (digest OR vital send OR pending approval OR “nothing actionable”)
6) If task-tracking exists: move task → review with a 1–2 sentence pointer + file path

That keeps the behavior but removes ~70% of the tokens.

Where to put the long subagent template instead

Option A (best): inline it only when spawning

When you do sessions_spawn, just include a short “raw collector spec” in the task message. You don’t need a stored template at all.

Option B: store it as a file, but don’t auto-inject

Create:

  • templates/subagent-raw-collector.md
#

and only read it right before spawning subagents (so you pay the tokens only when you actually use subagents).

If you paste your full current injected file, I can rewrite it end-to-end into a “<1k chars injected policy + optional templates file” version that keeps all your intent.

#

You’re basically writing an SOP + routing policy. To cut token burn, collapse it into (a) routing rules + (b) a short checklist and move anything “example-y / motivational / commands” into TOOLS.md or a template file.

Biggest cuts to make

  • Delete metaphors (“iceberg rule”) → 1 line max.
  • Merge “Task Flow” + “What YOU do…” + “Quality Standards” into one checklist.
  • Move the QMD command into TOOLS.md (so the exact CLI incantation isn’t paid for every turn). In injected text, keep: “Search QMD first”.

Optimized injected block (drop-in)

Put this in your injected AGENTS.md (or injections/AGENTS.md). It keeps your intent but is much cheaper:

# Scout — Researcher (Operating Rules)

Role: research → synthesize → route. No dead-end research.
# 

Always start: search team memory/QMD for the topic (see TOOLS.md) to avoid duplicate work.

Workflow:
1) Clarify the question if unclear.
2) Split into 3–5 sub-questions.
3) Spawn subagents as RAW COLLECTORS only (URLs, queries, verbatim quotes/data; no summaries).
4) You clean + dedupe + note contradictions + write the synthesis.
5) Save raw report: research/YYYY-MM-DD-topic.md (include sources).

Quality bar (before “done”):
- Every key claim has ≥1 real source link.
- Conflicts are explicitly noted.
- Output includes explicit takeaways (not just raw data).
# 
Routing (pick what applies, then act):
- General → update digest (memory/digest-YYYY-MM-DD.md) + notify Total.
- Health/wellness → sessions_send agent:vital:main: summary (2–3 sentences) + file path + why it matters to Jonathan.
- Buildable → add to PENDING_APPROVAL.md (template in templates/) + notify Total.
- Security concern → sessions_send agent:sentinel:main (summary + file path).

Task tracking (if board exists): comment with (what/where/key insight) then move task → review.

What to put in TOOLS.md instead (so it’s not injected “forever”)

In TOOLS.md, keep the exact QMD snippet:

  • qmd query "…" -c total-shared
  • any required env vars / caveats / where QMD index lives

If you want even lower burn

#

Remove the whole “Routing” block from injection and replace it with one line like:
“After saving the raw report, apply Routing (see templates/Routing.md)” — then read that file only when finishing a task.

If you paste your full combined SYSTEM.md, I can do a strict “<1200 chars injected / everything else moved to templates+TOOLS” pass and hand you the final file set + paths list.

#

These are perfect candidates to keep always injected — they’re short, high‑leverage, and prevent expensive mistakes. I’d only tighten the wording to remove the repeated “Never…”, and (optionally) rename the section to ## Red Lines so it’s visually obvious.

Here’s the compact version:

## Red Lines

- Route research to Total (don’t message Jonathan directly).
- Build ideas go to PENDING_APPROVAL.md (don’t create Forge tasks directly).
- “Done” requires a task comment: what you found + where it’s saved + what to do next.
- Sources must be verifiable; if not, mark as UNVERIFIED (no invented citations).

If you want to shave tokens even more, drop the names (“Jonathan/Forge”) from the injected rules and put those mappings in TOOLS.md—but honestly at 4 bullets, you’re already in the “cheap enough” zone.

keen lodge
#

I think you interpreted my messages as 4 separate ones can you give me the optimized one but now looking at the entire file i sent you

empty dockBOT
#

Got it — here’s a single optimized version that covers the entire spec you pasted (role, routing, quality bar, subagent usage, task flow, QMD, saving, hard rules), but rewritten to be tight enough to inject.

I’m also including (optional but recommended) two small template files you should not auto-inject (so you don’t pay for them every turn).

1) Injected file (optimized)

Save as: <workspace>/injections/AGENTS.md (or just merge into your root <workspace>/AGENTS.md)

# Scout — Researcher (Operating Rules)

Role: research → synthesize → route. Research that doesn’t reach an owner is wasted.

## Destinations / Routing
- General findings → Total (sessions_send)
# 
- Health/wellness → Vital (sessions_send agent:vital:main)
- Buildable opportunities → PENDING_APPROVAL.md + notify Total
- Security concerns → Sentinel (sessions_send)

## Red Lines (Hard Rules)
- Route research through Total (don’t send research directly to Jonathan).
- Don’t create Forge build tasks directly; use PENDING_APPROVAL.md.
- Never mark “done” without a task comment: what you found + where it’s saved + what to do next.
- Never fabricate sources. If you can’t verify, label as UNVERIFIED.

## Start of Task (always)
1) If unclear, ask a clarifying question.
2) Check team memory/QMD to avoid duplicate work (see TOOLS.md for exact command).

## Research Workflow (default)
# 
1) Split into 3–5 sub-questions.
2) Spawn subagents in parallel as **raw collectors only**:
   - Must return: URLs, search queries, verbatim quotes/data, and raw observations
   - Must NOT summarize or conclude
   - Use templates/subagent-raw-collector.md as the instruction scaffold
3) You do the synthesis:
   - dedupe + clean + organize
   - identify patterns + contradictions
   - produce actionable takeaways
4) Save raw report: `research/YYYY-MM-DD-topic.md` (include source URLs).

## Quality Bar (before “done”)
- Sources are real + verifiable (link per key claim).
- Conflicts are noted explicitly.
- Takeaways are explicit + actionable (not just a dump).
# 

## Output Actions (end every research task with the right one)
### A) General research → Digest → Total
- Append 3–5 bullets to: `memory/digest-YYYY-MM-DD.md`
  - what it is, why it matters to Jonathan, + 1–2 best links
- Notify Total that the digest was updated (batch; don’t spam).

### B) Health/wellness → Vital
Send to `agent:vital:main`:
- 2–3 sentence key finding
- file path to full research
- why it matters to Jonathan

### C) Buildable opportunity → PENDING_APPROVAL.md → Total
- Add entry to `PENDING_APPROVAL.md` using templates/PENDING_APPROVAL_TEMPLATE.md
# 
- Notify Total with the entry title + why it matters.

### D) Security concern → Sentinel
Send to Sentinel:
- short summary + severity
- file path + sources
- recommended next action

## Task Tracking (if a board exists)
- Comment with: what/where/next-action
- Move task → review

2) Template (NOT injected): subagent raw collector scaffold

#

Save as: <workspace>/templates/subagent-raw-collector.md

You are a raw data collector supporting Scout.

Research sub-question:
[SUB-QUESTION]

Rules:
- Collect raw data only. Do NOT summarize or conclude.
- Include every URL visited, every search query used, and verbatim quotes/data when possible.

Return format (repeat per source):
URL:
Search query used:
Data found (verbatim if possible):
# 
Notes (raw observations):

3) Template (NOT injected): PENDING_APPROVAL entry format

Save as: <workspace>/templates/PENDING_APPROVAL_TEMPLATE.md

## [Date] - [Finding Title]
**What:** [1–2 sentence description]
**Why it matters (Jonathan):** [why valuable]
**What Forge would build:** [specific implementation]
**Complexity:** [small/medium/large + why]
**Research file:** [path]
# 
**Status:** PENDING_APPROVAL

Hook/config reminder (to inject injections/AGENTS.md)

hooks: {
  internal: {
    enabled: true,
    entries: {
      "bootstrap-extra-files": {
        enabled: true,
        paths: ["injections/AGENTS.md"],
      },
# 
    },
  },
},

If you want, paste what you currently have in TOOLS.md (or what you want there for QMD + any absolute paths), and I’ll rewrite that too so it stays compact but still usable.

keen lodge
#

can you export everything you know about optimizing for tokens. ill pass that info to claude and have it rewrite my files.

empty dockBOT
#

Token Optimization Playbook (OpenClaw-focused)

Use this as a “rewrite spec” for Claude to slim your injected files and reduce ongoing token burn.

0) First principle: injected context costs every turn

Anything injected via bootstrap files (AGENTS/SOUL/TOOLS/USER/IDENTITY/HEARTBEAT/MEMORY) or via bootstrap-extra-files is paid on every model call (unless the provider prompt-cache hits, which still benefits from smaller/more stable prompts).

So the goal is:

  • keep always-injected text tiny and stable
  • move everything else to on-demand reads (templates/SOPs) or tools/memory search

Docs:

#

1) Know what’s actually in the context window

Every request includes (roughly):

  • System prompt (OpenClaw-owned) + tool list + skills metadata
  • Injected bootstrap files (your workspace files)
  • Conversation history
  • Tool calls + tool results
  • Attachments (images/audio transcripts)
  • Any compaction summaries / pruning artifacts

Action: use /context list (and /context detail) to see what’s expensive.

2) Keep injected files “policy-only”

Good injected content (high leverage / short):

#
  • roles + routing rules (“send to Total/Vital/Sentinel”)
  • red lines (“don’t fabricate sources”, “done requires comment”)
  • short checklists (“start of task”, “finish of task”)
  • stable identifiers (session keys, file naming conventions)

Bad injected content (token heavy / low ROI):

  • long templates (multi-paragraph forms)
  • verbose examples
  • motivational text / metaphors
  • repeated “every session read X” (especially when X is already injected)
  • absolute-path walls / giant command snippets

Rewrite rule of thumb:

  • injected file should be ~300–1500 tokens max (often much less)
  • everything else becomes a referenced file in templates/ or docs/
#

3) Don’t inject templates — store them and load only when needed

For things like:

  • subagent prompt scaffolds
  • approval-entry templates
  • “research report format”
  • SOPs (“step 1… step 12…”)

Store them in:

  • <workspace>/templates/<name>.md

Then, when needed, the agent can:

  • paste a shortened version into sessions_spawn(...) (often enough), or
  • read templates/<name>.md once at the moment it matters

This converts “every turn cost” → “only when used”.

#

4) Avoid duplicate bootstrap injections

If you use bootstrap-extra-files, remember: each extra injected AGENTS.md/TOOLS.md is additional permanent overhead.

Prefer:

  • one primary AGENTS.md per agent workspace
  • at most one extra injected file (only if you really need modularity)

5) Keep the system prompt cache-friendly (stability matters)

Provider prompt caching is strongest when the prefix is stable.

Avoid injecting “volatile” text into always-on files:

  • timestamps (“today/yesterday”, “it is now…”, “9am PST today…”)
  • daily changing content blocks
  • long frequently-updated notes in MEMORY.md (if you constantly edit it, you bust cache frequently)
#

Better patterns:

  • if it changes daily, store it in memory/YYYY-MM-DD.md and fetch via memory_search only when needed
  • schedule delivery via cron instead of injecting “what time is it” logic

6) Use OpenClaw knobs that directly reduce token waste

Bootstrap trimming:

  • agents.defaults.bootstrapMaxChars
  • agents.defaults.bootstrapTotalMaxChars
  • agents.defaults.bootstrapPromptTruncationWarning (reduce noise)

Images:

  • agents.defaults.imageMaxDimensionPx (downscale screenshots to reduce vision tokens)

Pruning:

  • agents.defaults.contextPruning (cache-ttl pruning trims old tool results from in-memory context)
#
  • prune old huge tool outputs; keep only recent + small

Compaction:

  • use /compact when sessions get huge
  • tune agents.defaults.compaction.* (reserve tokens, etc.)

Config reference: https://docs.openclaw.ai/gateway/configuration-reference

7) Control tool-output size (tool results are often the real killer)

Tool output can dwarf everything else.

Best practices:

  • when a tool returns a huge blob, immediately write it to a file and keep only:
    • filename/path
    • 5–10 bullet summary
#
  • “next actions”
  • ask subagents to return structured + bounded output (e.g., “max 10 items”, “max 20 lines”, “top 5 links”)
  • for raw dumps: save them to research/...md and only summarize in chat

8) Skills: keep them on-demand, not always loaded

OpenClaw injects only skill metadata, but if you over-enable skills you still inflate prompt size.

Patterns:

  • enable only relevant skills per agent
  • keep skill descriptions short
  • load SKILL.md only when needed (that’s already the recommended workflow)

9) Heartbeat/crons: keep them cheap and light

#

If you run heartbeats:

  • use agents.defaults.heartbeat.lightContext: true when possible
  • use cheaper models for heartbeat (don’t burn premium tokens on periodic checks)
  • keep heartbeat prompt short and avoid big injected context blocks

Docs: token-use page + config reference (heartbeat section)

10) “Rewrite spec” you can hand to Claude

Tell Claude to do this transformation:

  1. Produce Injected Policy File (AGENTS.md or injections/AGENTS.md) containing only:
    • role
    • routing destinations
    • red lines
    • start-of-task checklist
#
  • finish-of-task checklist
    • max ~1–1.5k tokens

  1. Produce Templates under templates/:

    • subagent raw collector prompt
    • PENDING_APPROVAL entry template
    • any SOPs / workflows / checklists longer than ~10 lines

  2. Move commands and absolute paths to TOOLS.md (still injected, but keep it concise):

    • QMD query command(s)
    • “where research files live”
    • session keys like agent:total:main, agent:vital:main

  3. Ensure the injected file contains references, not full text:

    • “use templates/subagent-raw-collector.md”
    • “use templates/PENDING_APPROVAL_TEMPLATE.md”