Skip to content

Lecture 37 - OpenClaw Case Study: System Prompt Architecture

Course: AI Agent Development 2026 | Previous: Lecture 36 | Next: Lecture 38


Modern agent systems are not controlled by one short prompt.

They are controlled by a prompt assembly system.

That system decides:

  • what identity the agent receives
  • what tools it knows how to use
  • what workspace context is injected
  • what safety guidance is present
  • what provider-specific tuning is added
  • what should stay stable for prompt caching
  • what should stay out of the prompt and be enforced by runtime policy

This lecture uses OpenClaw's system prompt design as the case study.

The important lesson is:

a production agent should not depend on a random provider default prompt; it should have an owned, inspectable, versioned prompt assembled by the application runtime


Learning objectives

By the end of this lecture, you should be able to:

  1. Explain why OpenClaw owns the system prompt instead of using provider defaults.
  2. Describe the major sections of an OpenClaw-style system prompt.
  3. Understand full, minimal, and none prompt modes.
  4. Explain how bootstrap files become Project Context.
  5. Understand why skills are listed compactly and loaded on demand.
  6. Separate advisory prompt safety from hard runtime enforcement.
  7. Design a cache-aware provider overlay.
  8. Inspect prompt size and context injection when debugging an agent.

1. Simple mental model

Think of a serious agent as a field engineer.

Before the engineer starts work, you do not just say:

Be helpful.

You give them an operating binder:

Who you are.
How to talk to users.
How to use tools.
Which workspace you are in.
What files contain project context.
What policies you must follow.
When to ask for help.
How to report completion.

In OpenClaw, the system prompt is that operating binder.

It is assembled before each agent run.

agent request
  -> resolve agent/session/workspace
  -> assemble OpenClaw-owned system prompt
  -> inject bootstrap context and skills list
  -> apply provider-specific small overlays
  -> run model

The model does not invent the operating binder.

OpenClaw builds it.


2. Why OpenClaw owns the system prompt

A provider default prompt is useful for a generic chat product.

It is not enough for a product that has:

  • tools
  • sessions
  • workspaces
  • sub-agents
  • cron jobs
  • long-running processes
  • provider plugins
  • local docs
  • memory files
  • sandbox behavior
  • gateway commands
  • user-specific persona files

OpenClaw owns the prompt so that behavior is consistent across models and providers.

The system can say:

  • "This is how OpenClaw agents use tools."
  • "This is where local docs live."
  • "This is the workspace."
  • "This is how sub-agents should be used."
  • "This is what bootstrap context was injected."
  • "This is what safety means in this runtime."

The provider still matters, but the product owns the agent contract.


3. Prompt assembly has several lifetimes

At the audited revision, a pure renderer (buildAgentSystemPrompt) consumes explicit inputs; a configured facade supplies agent options; runtime adapters gather live tools, workspace and provider facts. This separation keeps previews and execution aligned without making the renderer read mutable global configuration.

The exact sections depend on runtime, channel, enabled tools and prompt mode. Stable project instructions can remain above a cache boundary while changing tool catalogs and current-turn facts arrive through other layers. A list of section headings is not a universal byte-for-byte prompt, and a prompt snapshot is not necessarily the final raw provider request.

Use the pinned system-prompt source and the runtime's diagnostics to inspect the actual route. Provider-generated reasoning controls and executor authorization are separate from the prose assembled here.

4. Tooling section

The Tooling section teaches the model how work should be done inside this runtime.

It covers patterns such as:

  • use structured tools instead of pretending to act
  • prefer cron for future follow-ups instead of sleep loops
  • use process tools for long-running commands and logs
  • use sub-agents for larger parallel work
  • do not poll sub-agents in tight loops
  • use update_plan only when it is enabled and useful

This section is important because tool-using agents often fail in boring ways:

  • they say they did something but did not call the tool
  • they start a long process and lose the logs
  • they sleep inside a command instead of scheduling future work
  • they spawn too many agents for simple work
  • they update a plan repeatedly without doing work

The Tooling section converts product expectations into model-facing habits.


5. Execution Bias section

Execution Bias is the "finish the work" section.

It gives compact follow-through guidance:

  • act within the current turn when the request is actionable
  • continue until done or genuinely blocked
  • recover when a tool result is weak
  • check mutable state live instead of assuming
  • verify before finalizing

This section exists because many models default to advice.

A production engineering agent often needs action.

Compare:

Weak behavior:
"You could run the tests."

OpenClaw-style behavior:
"Run the tests, inspect the failure, patch the issue, rerun verification, then summarize."

Execution Bias does not mean reckless automation.

It means the agent should carry work through the runtime loop when it has enough permission and context.


6. Care guidance and enforcement

The current source includes Care guidance; the exact wording and sections depend on the runtime.

It tells the model not to bypass oversight, escalate privileges improperly, hide risky behavior, or seek control outside the user intent.

But this is a key production lesson:

prompt safety is advisory; runtime enforcement is mandatory

The system prompt can ask the model to behave safely.

Hard enforcement must come from:

  • tool policy
  • exec approvals
  • sandboxing
  • filesystem boundaries
  • channel allowlists
  • identity and permission checks
  • audit logs

If a command must never run, do not merely write "do not run it" in a prompt.

Block it in the tool layer.


7. Skills section

OpenClaw can inject a compact list of available skills.

The prompt does not paste every skill into the context.

It lists:

  • skill name
  • short description
  • location

Then the model is instructed to read the relevant SKILL.md only when needed.

That is the correct architecture.

Bad pattern:

Paste every skill file into every run.

Good pattern:

List available skills compactly.
Load the matching skill on demand.

This avoids token bloat and keeps unrelated skills from polluting the run.

Skills have their own sizing budget:

  • global default: skills.limits.maxSkillsPromptChars
  • per-agent override: agents.entries.*.skillsLimits.maxSkillsPromptChars

This is separate from other runtime context limits.

That separation matters because a skills list and a workspace bootstrap file are different kinds of context.


8. OpenClaw Self-Update section

OpenClaw can expose tools for safely inspecting and changing its own configuration.

The prompt teaches a controlled path:

config.schema.lookup
config.patch
config.apply
update.run

The model should inspect the schema before changing config.

It should patch narrowly.

It should apply through the supported gateway tool.

It should not rewrite protected execution policy keys casually.

This is a useful pattern for any self-modifying agent system:

self-update should be schema-driven, narrow, logged, and guarded

Do not give an agent raw config file mutation and hope the prompt keeps it safe.


9. Workspace and documentation sections

The Workspace section tells the agent where it is operating.

It usually reflects:

agents.defaults.workspace

The Documentation section tells the agent where local OpenClaw docs live and encourages consulting them first.

This is a subtle but important production pattern.

For a tool-rich local assistant, local docs are often more accurate than memory.

The prompt should point the model to the local source of truth:

If you need OpenClaw behavior, inspect local docs first.
Then act.

10. Project Context and bootstrap files

OpenClaw appends selected workspace files under Project Context.

These are bootstrap files such as:

  • AGENTS.md
  • SOUL.md
  • IDENTITY.md
  • USER.md
  • BOOTSTRAP.md
  • MEMORY.md

The goal is simple:

important identity and project context should be present without requiring the model to remember to read it

Example:

Project Context
  AGENTS.md -> project rules
  SOUL.md -> personality and voice
  AGENTS.md ## Tools -> project-specific tool guidance
  USER.md -> user preferences
  MEMORY.md -> durable compact memory

This is powerful, but it has a cost.

Large bootstrap files increase:

  • prompt size
  • compaction pressure
  • latency
  • cache invalidation risk
  • irrelevant context exposure

So OpenClaw trims injection.

Documented defaults include:

  • per-file max: agents.defaults.bootstrapMaxChars, default 20000
  • total injected max: agents.defaults.bootstrapTotalMaxChars, default 60000
  • truncation notice: built in and not configurable in the audited revision; detailed file/count diagnostics stay outside the concise model notice

The practical rule:

bootstrap files should be concise operating context, not a dumping ground


11. Memory files

MEMORY.md handling is runtime-specific. Native Codex normally uses memory tools on demand when available, with a bounded prompt fallback otherwise. Other harnesses can inject a bounded copy. The file on disk survives prompt truncation; what the model sees may be only part of it.

Daily memory files under memory/*.md are different.

They are not normally injected by default.

They are accessed on demand through memory tools such as:

memory_search
memory_get

This keeps normal runs small.

Recent daily memory may be prepended once in special bare /new or /reset turns, but it is not the default for every run.

This is the right tradeoff:

  • durable compact memory can be prompt context
  • large daily logs should be retrieved only when relevant

12. Prompt modes

promptMode is chosen by the runtime. full renders the applicable sections; minimal reduces context for delegated work; none retains only the base identity line.

Current minimal mode can retain Skills when supplied, as well as tooling, Care guidance, workspace/sandbox/runtime and injected context. It omits several parent-facing sections such as memory recall, model aliases, user identity, messaging and silent-reply guidance. The old rule “minimal always removes Skills” no longer describes this source.

A smaller prompt does not grant different permissions by itself. The executor still decides which tools and resources a child can access. Test both prompt visibility and actual denied operations.

13. Sub-agent bootstrap behavior

Current OpenClaw bootstrap filtering injects AGENTS.md for sub-agent sessions; the former AGENTS.md plus separate TOOLS.md list is outdated. Native Codex additionally has its own project-document discovery, including tool guidance inside AGENTS.md.

Distinguish configured agent workspace from execution folder. The latter's project AGENTS.md can supply project context; it does not automatically replace the configured persona and user memory with arbitrary files in the execution directory. Native managed app-server and other connections also differ in which parent-local persona instructions children inherit.

Worked test: put a harmless marker in configured persona, execution-folder AGENTS.md and an execution-folder USER.md. Inspect the parent/child prompt surfaces on your pinned route. Do not assume every file is loaded just because it exists. A text marker test demonstrates inclusion, not authorization.

14. Time handling and prompt-cache stability

The audited implementation puts the user's calendar date and time zone in current-turn Temporal Context, outside the stable system prompt. It refreshes the current turn without rewriting prior messages. The exact current timestamp can be requested through session_status when available.

This matters for prefix caches: changing an early byte can invalidate reuse even if the new information is tiny. But cache stability must not keep stale task facts. Put changing facts in the appropriate later carrier, preserve the full instruction semantics and measure actual cache behavior. agents.defaults.userTimezone configures the time zone; the old static “Current Date and Time” section is not a universal assembly rule.

15. Provider tuning and cache-aware overlays

Provider plugins are allowed to contribute small additions.

They should not replace the whole OpenClaw system prompt.

Provider plugins can:

  • replace named core sections such as interaction_style
  • replace tool_call_style
  • replace execution_bias
  • inject a stable prefix above the prompt-cache boundary
  • inject a dynamic suffix below the prompt-cache boundary

This gives model-family tuning without losing product control.

Example:

OpenClaw core prompt:
  stable runtime behavior

Provider overlay:
  small model-family guidance for GPT-5, Claude, local models, etc.

The OpenAI GPT-5 family overlay is described as keeping core execution rules small while adding guidance such as:

  • persona latching
  • concise output
  • tool discipline
  • parallel lookup
  • deliverable coverage
  • verification
  • missing context handling
  • terminal-tool hygiene

The architecture rule is:

provider tuning should be a small overlay, not a hostile takeover of the product prompt


16. Legacy hooks versus provider contributions

OpenClaw still supports a legacy before_prompt_build hook.

It can inject or mutate prompt material globally.

But for model-family behavior, provider contributions are preferred.

Why?

Because provider contributions can be cache-aware and scoped to the model family.

Use the right layer:

Need Better mechanism
Workspace-specific context Bootstrap files
Global prompt mutation before_prompt_build hook
Model-family tuning Provider contribution
Runtime security Tool policy and sandbox
User personality SOUL.md

17. Reply directives and heartbeat context

Output/attachment/reply directives depend on the channel and available tools. They do not replace the host's delivery routing. A visible text fragment is not proof that an external message was delivered; inspect the terminal receipt.

In the audited source, heartbeat monitor scratch is appended only to the scheduled heartbeat user message. There is no heartbeat-specific system-prompt section. Normal turns and delegated workers should not inherit heartbeat scratch merely because the gateway also runs scheduled checks. Test each route separately when changing prompt assembly.

18. Runtime and Reasoning sections

The Runtime section provides a compact one-line summary of the execution environment.

It can include:

  • host
  • OS
  • Node.js version
  • selected model
  • repo root if detected
  • thinking level

The Reasoning section explains visibility level and can hint at a /reasoning toggle.

This is not meant to be verbose.

It is a compact runtime signal so the model knows where it is operating.


19. Diagnostics: inspecting context

When an agent behaves strangely, inspect what it actually received.

OpenClaw supports commands such as:

/context list
/context detail

Use these to inspect:

  • which files were injected
  • raw size versus injected size
  • whether truncation happened
  • tool schema overhead
  • which context source dominates the prompt

This is critical for debugging.

Many "model problems" are actually context problems:

  • a bootstrap file is too large
  • a stale memory file is injected
  • a project rule is missing
  • a provider overlay is too strong
  • a sub-agent received full context instead of minimal context

Inspect the prompt assembly before blaming the model.


20. Example: smart speaker engineering agent

Imagine an OpenClaw-powered smart speaker assistant for a Jetson-based product lab.

The agent may need to:

  • inspect hardware notes
  • schedule follow-up tests
  • run shell commands
  • spawn a sub-agent to research codecs
  • remember user preferences
  • avoid unsafe GPIO or power commands
  • summarize logs

An OpenClaw-style system prompt might assemble this:

Tooling:
  Use process tools for long-running audio tests.
  Use cron for future lab reminders.
  Spawn sub-agents for isolated research.

Execution Bias:
  Run available checks before answering.
  Verify file paths and hardware state live.

Safety:
  Do not bypass exec policy.
  Do not change protected power or network settings without approval.

Workspace:
  /home/lab/smart-speaker

Project Context:
  AGENTS.md: lab rules
  AGENTS.md ## Tools: audio test commands
  USER.md: preferred report format
  MEMORY.md: concise project memory

Runtime:
  Jetson Orin Nano, Linux, local model provider, reasoning medium

Notice what is not in the prompt:

  • every past lab log
  • every available skill file
  • every daily memory file
  • raw policy implementation
  • secrets

The prompt gives the model the operating contract.

The runtime enforces the dangerous boundaries.


21. Common design mistakes

Mistake 1: putting everything in the system prompt

Large prompts feel powerful, but they become slow and noisy.

Use retrieval, skills, memory search, and local docs instead.

Mistake 2: relying on prompt safety alone

If a tool action is dangerous, gate it in the tool layer.

Prompt wording is not a permission system.

Mistake 3: giving sub-agents full context

Sub-agents should receive bounded context for bounded work.

Full identity and memory can distract them.

Mistake 4: putting live timestamps above the cache boundary

High-churn values reduce cache stability.

Expose exact time through tools when needed.

Mistake 5: letting provider plugins replace the product prompt

Provider overlays should tune.

They should not own the product contract.


22. Design exercise

Design a system prompt strategy for a local AI hardware lab assistant.

The assistant can:

  • answer questions
  • inspect local Markdown docs
  • run safe shell commands
  • schedule follow-ups
  • use a sub-agent for research
  • remember hardware inventory

Answer these:

  1. Which sections belong in the full prompt?
  2. Which sections should be omitted from sub-agent minimal prompts?
  3. Which files should be bootstrap-injected?
  4. Which information should be retrieved on demand instead of injected?
  5. Which safety requirements must be enforced by tools rather than prompt text?
  6. Which provider-specific guidance should be a small overlay?
  7. How will you inspect prompt size and truncation?

If you cannot answer these, your agent system is not yet operationally mature.


Key takeaways

  • OpenClaw owns and assembles the system prompt for each agent run.
  • The system prompt is a runtime contract, not a generic chat instruction.
  • Provider plugins should add small cache-aware overlays, not replace the full prompt.
  • Full mode is for main agents; minimal mode is for bounded sub-agents; none mode is for rare low-prompt cases.
  • Bootstrap files provide Project Context, but they must stay concise.
  • Skills should be listed compactly and loaded on demand.
  • Exact time should come from tools when needed so the stable prompt remains cache-friendly.
  • Prompt safety is advisory; hard safety belongs in runtime controls.
  • Context inspection is a first-class debugging skill.

References


Next: Lecture 38