How the System Prompt is Built

+15 Mana ✨
OpenClaw System Prompt Architecture(DOCUMENTATION)OpenClaw Token Management Guide(DOCUMENTATION)

Introduction

The system prompt is the complete set of instructions that the language model receives before it processes your message. In OpenClaw, this prompt is not a single file you write — it is assembled automatically from multiple sources. Understanding how these pieces come together gives you precise control over what the model sees and prioritizes.

Key Concepts

  • Fixed Sections: Permanent parts of the system prompt that OpenClaw always includes (tooling definitions, safety guidelines, skills, workspace context)
  • Bootstrap File Injection: Your personalization files (SOUL.md, IDENTITY.md, etc.) are inserted into specific positions within the prompt
  • Token Limits: Individual bootstrap files are capped at 20,000 tokens, and the total system prompt cannot exceed 150,000 tokens
  • Section Ordering: The sequence in which sections appear affects model attention — earlier sections receive stronger weight
  • Runtime Sections: Dynamic content added at runtime based on the current conversation state (active tools, docs, session context)

Real World Context

An agent has a detailed SOUL.md, extensive AGENTS.md, several loaded skills, and comprehensive tool documentation. When the total system prompt approaches 150K tokens, something has to give. Understanding the prompt architecture lets you make informed decisions about what to keep, trim, or restructure to stay within budget while preserving the most important instructions.

Deep Dive

OpenClaw assembles the system prompt in a specific order. Each section occupies a defined position:

markdown
System Prompt Assembly Order:
1. Safety & Compliance    (fixed, always first)
2. Identity & Persona     (IDENTITY.md + SOUL.md)
3. User Context           (USER.md)
4. Operating Instructions (AGENTS.md)
5. Tool Definitions       (auto-generated from registered tools)
6. Tool Conventions       (TOOLS.md)
7. Skills                 (loaded SKILL.md files)
8. Workspace Context      (project files, directory structure)
9. Documentation          (indexed docs, knowledge base)
10. Memory                (MEMORY.md)
11. Runtime State         (session context, active conversation)

This ordering is intentional. Safety guidelines come first because they must override everything else. Identity and persona come next because they shape every subsequent interpretation. Memory comes near the end because it is supplementary context, not core instruction.

Each bootstrap file is subject to a hard token limit:

markdown
Per-file token limits:
- Each bootstrap file: maximum 20,000 tokens
- Total system prompt: maximum 150,000 tokens

If a single bootstrap file exceeds 20,000 tokens, it is truncated from the end. This means content at the top of your files is always preserved, while content at the bottom may be cut. This is another reason to place your most important instructions early in each file.

When the total system prompt exceeds 150,000 tokens, OpenClaw applies a priority-based trimming strategy. Lower-priority sections (documentation, workspace context) are reduced before higher-priority sections (safety, identity, operating instructions) are touched.

Here is an example of how the assembled prompt looks conceptually:

markdown
[SAFETY & COMPLIANCE]
You must never generate harmful content...

[IDENTITY]
Name: Forge
Role: Engineering Assistant
...

[PERSONA]
You are concise, technically precise...
(contents of SOUL.md)

[USER CONTEXT]
User: Sarah Chen, Staff Backend Engineer...
(contents of USER.md)

[OPERATING INSTRUCTIONS]
Code Standards: Use custom error wrapper...
(contents of AGENTS.md)

[TOOLS]
Available tools: deploy, database-query, file-search...
(auto-generated tool definitions)

[TOOL CONVENTIONS]
deploy: Always use --dry-run first...
(contents of TOOLS.md)

[SKILLS]
Skill: git-commit-helper
...

[WORKSPACE]
Project structure: src/, internal/, docs/...

[DOCUMENTATION]
Indexed documentation entries...

[MEMORY]
Previous architectural decisions...
(contents of MEMORY.md)

[RUNTIME]
Current session: 14 messages, last active 2m ago

This conceptual view shows how your bootstrap files are just part of a larger system prompt. The model sees all of this context before processing your message.

Common Pitfalls

  • Assuming your bootstrap file is the entire prompt: Your files are injected alongside safety rules, tool definitions, skill docs, and runtime state. They share the token budget with all these other sections.
  • Placing critical instructions at the end of large files: If a file approaches the 20K token limit, content at the bottom may be truncated. Always front-load important instructions.
  • Ignoring the total token budget: A detailed AGENTS.md plus extensive TOOLS.md plus many loaded skills can push the total past 150K tokens, causing lower-priority sections to be trimmed.

Best Practices

  • Front-load critical content: Put your most important instructions in the first few hundred tokens of each bootstrap file.
  • Monitor your token usage: Use openclaw prompt stats to see how much of the 150K budget each section consumes.
  • Trim aggressively: If a bootstrap file exceeds 10K tokens, review it for content that could be moved to MEMORY.md or documentation indexes instead.

Summary

  • The system prompt is assembled from 11 sections in a fixed order, starting with safety and ending with runtime state
  • Bootstrap files are injected into specific positions alongside auto-generated tool definitions, skills, and workspace context
  • Each bootstrap file has a hard limit of 20,000 tokens; the total system prompt is capped at 150,000 tokens
  • Content ordering matters: earlier sections and content at the top of files receives stronger model attention
  • Use openclaw prompt stats to monitor token usage across all sections
✓ Completed