How OpenClaw Builds Its System Prompt and How to Customize It

A performance analysis of 49 OpenClaw requests on a Qwen3-Coder-30B local model revealed something counterintuitive: the slowest requests (10 to 16 seconds each) had nothing to do with model size or query complexity. They correlated with system prompt changes. Stable prompts returned in 1 to 2 seconds. The difference was entirely about whether the LLM's key-value cache could reuse the previous prompt prefix.

That 10x latency gap exists because OpenClaw rebuilds its system prompt for every agent run. The prompt is not a fixed string you paste into a config file. It is a composite document assembled from tool catalogs, workspace files, runtime metadata, and user settings. When any component shifts position or changes content, the cache prefix breaks and the model reprocesses thousands of tokens from scratch.

Understanding how OpenClaw constructs this prompt gives you two things: the ability to customize agent behavior without forking the source code, and the knowledge to keep your prompts cache-stable so you avoid paying that 10x penalty on every turn.

OpenClaw builds its system prompt through three layers, each adding a different kind of context.

Tier 1: buildAgentSystemPrompt

This is the pure renderer. It takes explicit inputs and produces structured prompt sections. Think of it as the template engine: given a set of parameters, it outputs the same prompt every time. The sections it produces include tooling guidance, execution bias, safety reminders, skills metadata, workspace configuration, and output formatting directives.

Tier 2: resolveAgentSystemPromptConfig

This layer resolves configuration-backed settings into concrete values. It reads your OpenClaw config and translates knobs like owner display name, TTS hints, model aliases, memory citation mode, and delegation mode into prompt fragments that Tier 1 can render.

Tier 3: Runtime Adapters

The final layer gathers live facts that only exist at execution time: the current tool catalog, sandbox state, provider-specific capabilities, context files from your workspace, and any plugin contributions. Runtime adapters call the prompt facade with all of this context, and the facade invokes Tiers 1 and 2 to produce the final prompt.

The result is a prompt that typically runs 5,000 to 10,000 tokens for a standard workspace. Heavier configurations with many skills and large context files can push well past that range.

The final system prompt is organized into named sections. Not every section appears in every run. OpenClaw uses three prompt modes that control inclusion:

• Full mode (default for primary agents): includes all sections
• Minimal mode (sub-agents): strips memory recall, self-update, model aliases, user identity, output directives, messaging, and heartbeats
• None mode: a single identity line with no additional context

In full mode, the prompt includes these core sections:

Tooling. A structured list of available tools with usage patterns. Tool names are case-sensitive, and the prompt reminds the model to call them exactly as listed.

Execution bias. Follow-through guidance for actionable requests. This tells the model to complete tasks rather than asking clarifying questions when the intent is clear.

Safety. Guardrail reminders. These are advisory, not enforced at the inference level.

Skills. A compact list of available skill files with names, descriptions, and paths. The model loads a skill's SKILL.md on demand rather than injecting all skill content into the prompt.

Workspace configuration. The working directory, documentation paths, and bootstrap file indicators.

Runtime context. Host OS, model name, repo root, thinking level, timezone (but not a live clock, which would break caching), and reasoning visibility settings.

Context files. This is where most customization happens. OpenClaw injects workspace files in a fixed priority order, from AGENTS.md (priority 10) through MEMORY.md (priority 70). Each file handles one concern, and the priority determines where it lands in the prompt.

Give your OpenClaw agents persistent, searchable storage

generous storage workspace with Intelligence Mode for semantic search and RAG. No credit card, no trial expiration. Connect via the Fastio MCP server.

Start 14-Day Trial

OpenClaw's primary customization mechanism is a set of markdown files that get injected into the system prompt at build time. You do not need to edit OpenClaw's source code or write custom prompt templates. Drop a file in your workspace root, and it becomes part of every agent run in that workspace.

Here is the injection order and what each file controls:

AGENTS.md (priority 10) sets core guidelines and standing orders. This is the highest-priority context file, meaning its instructions take precedence when they conflict with lower-priority files. Use it for repository-wide rules, hard policies, and behavioral constraints that should apply to every agent session.

SOUL.md (priority 20) controls personality and tone. If you want your agent to be terse, formal, casual, or domain-specific in its language, this is where you define that. OpenClaw treats SOUL.md as the personality layer, separate from instructions.

IDENTITY.md (priority 30) sets the agent's name and persona constraints. If you are running multiple agents with different identities in the same workspace, each gets its own IDENTITY.md.

USER.md (priority 40) stores user-specific preferences and history. This file tells the agent who it is talking to, what that person's role is, and any standing preferences for communication style or output format.

TOOLS.md (priority 50) provides tool usage instructions. When your workspace has external tools available through skills or integrations, TOOLS.md tells the agent how to use them properly.

BOOTSTRAP.md (priority 60) contains first-run setup instructions. OpenClaw only injects this file during workspace initialization, not on every run.

MEMORY.md (priority 70) provides memory system context. In non-Codex uses, this file is injected directly. In the Codex use, MEMORY.md is accessed on demand through memory_search and memory_get tools to save tokens.

Sub-agent sessions only receive AGENTS.md and TOOLS.md. This keeps sub-agent prompts lean, which matters for both cost and cache performance.

Each file has a token budget, and OpenClaw enforces both per-file and total character limits across all context files. If your combined context exceeds the total budget, OpenClaw truncates the overflow and can optionally warn you when truncation occurs.

Beyond context files, OpenClaw exposes several configuration knobs that affect what ends up in the system prompt. You set these through the OpenClaw configuration system.

Workspace path (agents.defaults.workspace): sets the working directory for all file operations. This value appears in the Workspace section of the prompt.

Timezone and time format (agents.defaults.userTimezone, agents.defaults.timeFormat): the prompt includes a "Current Date & Time" section with timezone only. OpenClaw deliberately omits a live clock to keep this section cache-stable. If the agent needs the current time, it calls the session_status tool instead.

Delegation mode (agents.defaults.subagents.delegationMode): controls how the agent handles requests that could be delegated to sub-agents. The default "suggest" mode has the agent propose delegation rather than acting on it automatically.

Heartbeat section (agents.defaults.heartbeat.includeSystemPromptSection): when enabled, the prompt includes a heartbeat section for proactive check-ins. Because heartbeat content changes frequently, OpenClaw places it in the volatile suffix (below the cache boundary) to prevent it from invalidating the stable prefix.

Skills budget (skills.limits.maxSkillsPromptChars and per-agent overrides): caps how much of the prompt the skills list can consume. If you have dozens of skills installed, this prevents the skills metadata from crowding out workspace context.

Context injection strategy (agents.defaults.contextInjection): controls how dynamic context like HEARTBEAT.md is injected. Options are "always," "continuation-skip" (saves tokens on safe turns by skipping injection), and "never."

Context limits (agents.defaults.contextLimits.*): fine-grained controls over runtime excerpt sizing for different content types.

These knobs let you tune the prompt's size, content, and caching behavior without writing a single line of prompt text yourself.

OpenClaw splits every system prompt into two zones separated by an internal cache boundary marker.

The stable prefix sits above the boundary. It includes tool definitions, skills metadata, workspace files, and static configuration. This content rarely changes between turns, so the LLM's KV cache can reuse it.

The volatile suffix sits below the boundary. It holds channel-specific data like messaging context, heartbeat content, group chat state, and per-turn metadata. This content changes frequently, but because it comes after the stable prefix, those changes do not invalidate the cached prefix tokens.

To keep the stable prefix stable, OpenClaw normalizes prompt fingerprints before sending them to the model. This normalization handles whitespace differences, line ending variations, hook-added context, and runtime capability ordering. Two prompts that are semantically identical but differ in formatting will produce the same fingerprint, so they share cached state.

The tool catalog gets special treatment. OpenClaw sorts MCP tool definitions deterministically before registration, so if your MCP server returns tools in a different order between calls, the prompt stays byte-identical and the cache holds.

Version 2026.4.5 improved this normalization to cover more edge cases, reducing unnecessary cache invalidation for users running local models. The practical impact: local model users who previously saw cache hit rates around 16% due to prompt ordering issues can now achieve 95% or higher with proper configuration.

Practical tips for cache optimization:

• Keep volatile content below the cache boundary. If you are adding custom context that changes between turns, make sure it lands in the volatile suffix rather than the stable prefix.
• Use cacheRetention: "long" for baseline agents that run extended sessions.
• Set heartbeat intervals (e.g., every: "55m") to keep caches warm during idle periods.
• Enable contextPruning.mode: "cache-ttl" to prevent oversized history from re-caching after idle periods.
• For bursty agents that see infrequent reuse, consider disabling caching entirely to avoid the overhead of cache writes that never get read.

Provider plugins can also inject content at specific positions relative to the cache boundary. Plugins can replace named core sections (interaction_style, tool_call_style, execution_bias) or inject stable content above the boundary and dynamic content below it, all without replacing the full prompt.

OpenClaw agents generate files, analysis results, and structured data that need to live somewhere after the session ends. Local filesystems work for solo development, but they break down when agents hand off work to humans or when multiple agents need to read each other's output.

S3 and similar object stores solve the persistence problem but add infrastructure you have to manage: bucket policies, access keys, versioning configuration, and a separate search layer if you want to find anything later.

Fastio gives OpenClaw agents a workspace that handles persistence, search, and handoff in one layer. The Business Trial includes 50 GB of storage, included credits, and 5 workspaces with no credit card required. Agents access workspaces through the Fastio MCP server via Streamable HTTP at /mcp or legacy SSE at /sse.

The advantage for OpenClaw workflows specifically: when an agent builds a workspace with documents, shares, and structured data, it can transfer ownership to a human through a claim link. The agent keeps admin access for ongoing maintenance, and the human gets full control of the workspace. Files uploaded to a workspace with Intelligence Mode enabled are automatically indexed for semantic search and RAG chat, so the handoff includes not just files but a searchable knowledge base.

For teams running multiple OpenClaw agents that produce output for the same project, Fastio's file locks prevent conflicts during concurrent writes, and the audit trail captures every file operation, membership change, and AI action for compliance review.