OpenClaw Agent System Prompt Architecture Explained (9 Layers)

Author: huangserva (@servasyy_ai)
Published: March 5, 2026
Source: X/Twitter

---

This document provides a detailed breakdown of the complete System Prompt structure that OpenClaw Agent sends to LLMs.

Version

• Version: v2.1
• Updated: 2026-03-05

Quick Start for Beginners

1. Layer 7 (Workspace Files) - Configuration files you can directly edit
2. Layer 8 (Bootstrap Hook) - Scripts you can write to dynamically inject content
3. Other layers - Auto-generated by the framework, understand but don't modify

Common Use Cases

• Want to define Agent identity? → Edit Layer 7's IDENTITY.md
• Want to add project documentation? → Use Layer 8's bootstrap-extra-files Hook
• Want to inject real-time context? → Use Layer 8's before_prompt_build Hook
• Want to control file size? → Adjust bootstrapMaxChars configuration

The 9 Layers

Layer 1: Identity & Core Instructions

Analogy: Like the "Instructions" section of an operating manual - tells the LLM who you are, what you can do, and how you should respond.

Design Trade-off:

• Balance: Flexibility vs Consistency
• Decision: Framework generates uniformly to ensure consistent base behavior across all Agents
• Benefits:
  • Users don't need to repeat basic rules for each Agent
  • All Agents automatically gain new capabilities when framework upgrades
  • Reduces configuration error risk
• Cost:
  • Users cannot modify these core rules
  • Special behaviors can only be achieved indirectly through Layer 7/8

Layer 2: Tool Definitions

Analogy: Like a Swiss Army knife's tool list - tells the LLM what tools you have, what each does, and how to use them.

Why JSON Schema?

• Balance: Flexibility vs Type Safety
• Decision: Use strict JSON Schema to define tool parameters
• Benefits:
  • LLM can understand tool usage more accurately
  • Framework can validate parameters before calling
  • Auto-generate documentation and type definitions
• Cost:
  • Adding new tools requires complete Schema
  • Cannot support fully dynamic parameter structures

Layer 3: Skills Catalog

Analogy: Like a restaurant's "specialty menu" - tells the LLM what professional domain "recipes" are available to call.

Why directory scanning instead of manual registration?

• Balance: Flexibility vs Maintenance Cost
• Decision: Auto-scan ~/development/openclaw/skills/ directory
• Benefits:
  • Adding new Skills only requires placing in directory, no config changes
  • All Agents automatically get new Skills
  • Reduces configuration error risk
• Cost:
  • Cannot precisely control which Skills each Agent can use
  • All Skills injected into System Prompt (increases token consumption)

Layer 4: Model Aliases

Analogy: Like "keyboard shortcuts" - give complex model paths short aliases for easy calling.

Why model aliases?

• Balance: Flexibility vs Readability
• Decision: Allow users to define short aliases for commonly used models
• Benefits:
  • Simplify model calls (glm-5 instead of zhipu/glm-5)
  • Support multi-Provider switching (same alias can map to different Providers)
  • Convenient for A/B testing and model migration
• Cost:
  • Need to maintain alias configuration file
  • May cause confusion (same alias in different Agents might point to different models)

Layer 5: Protocol Specifications

Analogy: Like "traffic rules" - define standard protocols for Agent-system interaction.

Why protocol specifications?

• Balance: Freedom vs Consistency
• Decision: Define standardized interaction protocols (Silent Replies, Heartbeats, Reply Tags, etc.)
• Benefits:
  • Ensure consistent behavior across all Agents
  • Support automated monitoring and health checks
  • Simplify multi-Agent collaboration
• Cost:
  • Limits Agent's free expression
  • Requires LLM to strictly follow protocol (may be ignored)

Layer 6: Runtime Context

Analogy: Like a "dashboard" - tells the LLM the real-time status of the current runtime environment.

Why inject runtime info every time?

• Balance: Token Consumption vs Context Accuracy
• Decision: Inject latest runtime state with each request
• Benefits:
  • LLM knows current time (avoid time confusion)
  • LLM knows current model (avoid capability misjudgment)
  • LLM knows current environment (avoid path errors)
• Cost:
  • Each request consumes ~2KB tokens
  • Information may contain redundancy

Layer 7: Workspace Files (User-Editable)

Analogy: Like "your work notes" - static configuration files you can directly edit.

Why is only this layer statically editable?

• Balance: Framework Stability vs User Freedom
• Decision: Separate "change" from "unchanging" - framework layer ensures consistency, user layer allows personalization
• Benefits:
  • Users can define Agent identity, work specifications, memory
  • Framework upgrades won't break user configuration
  • Config files can be version controlled, backed up, shared
• Cost:
  • Users cannot modify framework core behavior
  • Need to learn TELOS framework and file structure

Core Files:

• IDENTITY.md - Agent identity and persona
• MEMORY.md - Long-term memory and learned patterns
• TOOLS.md - Tool documentation and usage notes
• AGENTS.md - Workspace index and guidelines
• USER.md - Information about the human user

Layer 8: Bootstrap Hooks (Dynamic Injection)

Analogy: Like "plugins" - scripts that run at startup to dynamically inject content.

Available Hooks:

• bootstrap-extra-files - Add additional files to workspace context
• before_prompt_build - Inject real-time context before prompt construction

Layer 9: Message History

Analogy: Like "conversation transcript" - the actual back-and-forth between user and Agent.

---

Conclusion

Understanding these 9 layers helps you:

1. Know what you can customize (Layers 7-8)
2. Understand what the framework handles automatically (Layers 1-6, 9)
3. Make informed decisions about Agent configuration
4. Debug issues more effectively

For more information, visit the OpenClaw documentation.

---

This article was originally published by huangserva on X/Twitter. Republished with attribution.