This document provides a detailed breakdown of the complete System Prompt structure sent by OpenClaw Agent to the LLM.
Version:
v2.1
Update Time:
2026-03-05
Overall Architecture Diagram
Quick Navigation (TL;DR)
Must-read for Beginners:
- Layer 7 (Workspace Files) - Configuration files you can edit directly.
- Layer 8 (Bootstrap Hook) - Where you can write scripts to dynamically inject content.
- Other layers are automatically generated by the framework; just understand them.
Common Needs:
- Want to define Agent identity? → Edit IDENTITY.md in Layer 7.
- Want to add project documentation? → Use the bootstrap-extra-files Hook in Layer 8.
- Want to inject real-time context? → Use the before_prompt_build Hook in Layer 8.
- Want to control file size? → Adjust the bootstrapMaxChars configuration.
Layer 1: OpenClaw Framework Core
Analogy
Like the "Instructions for Use" section of an operation manual—telling the LLM who you are, what you can do, and how you should respond.
Components
Practical Example
You are running as a "Creative Partner," an AI content creation expert Agent.
Current Time: 2026-03-05 14:37:00 CST
=== Tool Calling Specification ===
- Use XML-style tool calling format.
- Each tool call must include a unique tool_call_id.
- Tool results are returned via <tool_result> tags.
- Consider AbortSignal when executing tools to support cancellation.
=== Safety Boundaries ===
- Strictly prohibited from executing destructive operations (rm -rf, formatting, etc.).
- Sensitive user information must be encrypted when handled.
- Prohibited from sending messages to unauthorized channels.
Design Trade-offs
Why design it this way?
- Trade-off: Flexibility vs. Consistency
- Decision: Unified generation at the framework layer ensures consistent basic behavior for all Agents.
- Benefits: Users don't need to repeat basic rules for every Agent. All Agents automatically gain new capabilities when the framework upgrades. Reduces the risk of configuration errors.
- Cost: Users cannot modify these core rules. Special behaviors must be implemented indirectly via Layer 7/8.
Layer 2: Tool Definitions
Analogy
Like a Swiss Army knife's tool list—telling the LLM what tools you have, what each does, and how to use them.
Components
Tool Definition Example
{
"name": "read",
"description": "Read file content. Supports text files and images (jpg/png/gif/webp). Images are sent as attachments. Text output is limited to 2000 lines or 50KB.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File path (relative or absolute)"
},
"offset": {
"type": "number",
"description": "Starting line number (1-indexed)"
},
"limit": {
"type": "number",
"description": "Maximum lines to read"
}
},
"required": ["path"]
}
}
Design Trade-offs
Why use JSON Schema?
- Trade-off: Flexibility vs. Type Safety
- Decision: Use strict JSON Schema to define tool parameters.
- Benefits: LLM understands tool usage more accurately. The framework can validate parameters before calling. Automatically generates documentation and type definitions.
- Cost: Adding new tools requires writing a full Schema. Cannot support completely dynamic parameter structures.
Layer 3: Skills Registry
Analogy
Like a restaurant's "Specialty Menu"—telling the LLM which professional "recipes" are available to call.
Design Trade-offs
Why use directory scanning instead of manual registration?
- Trade-off: Flexibility vs. Maintenance Cost
- Decision: Automatically scan the ~/development/openclaw/skills/ directory.
- Benefits: Adding a new Skill only requires placing it in the directory; no config changes needed. All Agents automatically get the new Skill. Reduces configuration error risks.
- Cost: Cannot precisely control which Skills are available to each Agent. All Skills are injected into the System Prompt (increasing token consumption).
Components
Layer 4: Model Aliases
Analogy
Like "Shortcuts"—giving complex model paths short aliases for easy calling.
Design Trade-offs
Why are model aliases needed?
- Trade-off: Flexibility vs. Readability
- Decision: Allow users to define short aliases for commonly used models.
- Benefits: Simplifies model calls (glm-5 instead of zhipu/glm-5). Supports switching between multiple Providers (same alias can map to different Providers). Facilitates A/B testing and model migration.
- Cost: Requires maintaining an alias configuration file. Can cause confusion (the same alias might point to different models for different Agents).
Components
Practical Example
In the System Prompt, model aliases are displayed as:
Model Aliases
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
LLMs can use aliases to switch models: /model glm-5
Layer 5: Protocol Specifications
Analogy
Like "Traffic Rules"—defining standard protocols for Agent interaction with the system.
Design Trade-offs
Why are protocol specifications needed?
- Trade-off: Freedom vs. Consistency
- Decision: Define standardized interaction protocols (Silent Replies, Heartbeats, Reply Tags, etc.).
- Benefits: Ensures consistent behavior across all Agents. Supports automated monitoring and health checks. Simplifies multi-Agent collaboration.
- Cost: Limits the Agent's freedom of expression. Requires the LLM to strictly follow protocols (which might be ignored).
Components
Practical Example
Silent Replies Example:
User: Received
Agent: NO_REPLY
Heartbeats Example:
System: [Heartbeat Poll]
Agent: HEARTBEAT_OK
Reply Tags Example:
Agent: [[reply_to_current]] Task completed ✓
Layer 6: Runtime Info
Analogy
Like a "Dashboard"—telling the LLM the real-time status of the current running environment.
Design Trade-offs
Why inject runtime info every time?
- Trade-off: Token Consumption vs. Context Accuracy
- Decision: Inject the latest runtime status with every request.
- Benefits: LLM knows the current time (avoids time confusion). LLM knows the current model (avoids capability misjudgment). LLM knows the current environment (avoids path errors).
- Cost: Consumes ~2KB tokens per request. Information may contain redundancy.
Components
Practical Example
Runtime
Layer 7: Workspace Files ★ User Controllable
Analogy
Like "Your Work Notes"—these are static configuration files you can edit directly.
Design Trade-offs
Why is only this layer statically editable?
- Trade-off: Framework Stability vs. User Freedom
- Decision: Separate the "changing" from the "unchanging"; the framework layer ensures consistency while the user layer allows personalization.
- Benefits: Users can define Agent identity, work specs, and memory. Framework upgrades won't break user configs. Config files can be version-controlled, backed up, and shared.
- Cost: Users cannot modify core framework behavior. Requires learning the TELOS framework and file structure.
Core Files
Layer 8: Bootstrap Hook System ★ User Controllable
Analogy
Like a "Programmable Syringe"—you can write scripts to dynamically inject content into the System Prompt at runtime.
Design Trade-offs
Why is a Hook system needed?
- Trade-off: Simplicity of Static Config vs. Flexibility of Dynamic Injection
- Decision: Provide a dynamic Hook mechanism alongside static Workspace Files.
- Benefits: Can dynamically adjust injected content based on context (channel, sender, time). Can execute shell commands and inject output (e.g., current weather, Git status). Can read external files and inject them (e.g., project docs, API docs). Supports conditional logic (if/else).
- Cost: Requires learning Hook system syntax and trigger mechanisms. Hook script errors can cause System Prompt anomalies. Increases system complexity.
Four Hook Mechanisms
- agent:bootstrap Hook (Internal Hook System)
Trigger Location: applyBootstrapHookOverrides() in bootstrap-hooks.ts
Capabilities:
- Full control over the bootstrapFiles array.
- Can add, delete, or modify files.
- Can reorder files.
- Can modify file content.
Who can register:
- OpenClaw plugins.
- Workspace Hooks (~/.openclaw/workspace-*/hooks/ directory).
- Internal modules.
Code Example:
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// Full control over bootstrapFiles array
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "Custom Content" }
];
});
- bootstrap-extra-files Hook (Bundled Hook)
Trigger Location: handler.ts in hooks/bundled/bootstrap-extra-files/
Capabilities:
- Only appends files; does not modify existing ones.
- Specifies extra files via configuration file.
Config Example:
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
Applicable Scenarios:
- Need to inject project-specific context files.
- Don't want to modify the default 8 Bootstrap files.
- Need to dynamically load extra documentation.
- before_prompt_build Hook (Plugin Hook)
Trigger Location: runBeforePromptBuild() in attempt.ts
Capabilities:
- Modifies the final prompt (after system prompt construction, before sending to LLM).
- Can prepend context (add content before the prompt).
- Can override systemPrompt.
Event Data:
{
prompt: string; // User input
messages: unknown[]; // Session message history
}
Return Value:
{
prependContext?: string; // Content added before the prompt
systemPrompt?: string; // Overrides the system prompt
}
Applicable Scenarios:
- Need to dynamically adjust prompt based on session history.
- Need to inject real-time context (e.g., current time, weather).
- Need to completely replace the system prompt.
- bootstrapMaxChars / bootstrapTotalMaxChars (Config Item)
Type: Configuration item (not a hook)
Capabilities:
- Controls character budget.
- Single file default: 20K.
- Total default: 150K.
- Excess is truncated by taking the first 70% + last 20%.
Config Location:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
Practical Advice
Scenario 1: I want to add project documentation
Recommended Solution: bootstrap-extra-files
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
Scenario 2: I want to dynamically load files based on task type
Recommended Solution: Custom agent:bootstrap Hook
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
const sessionKey = context.sessionKey;
// Load different files based on session type
if (sessionKey.includes("coding")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
Scenario 3: I want to inject real-time context (like current time)
Recommended Solution: before_prompt_build Hook
on("before_prompt_build", (event, ctx) => {
return {
prependContext: Current Time: ${new Date().toISOString()}
};
});
Layer 9: Inbound Context
Analogy
Like "Real-time Traffic Info"—dynamically injects context information of the current conversation with every request.
Design Trade-offs
Why inject context every time?
- Trade-off: Token Consumption vs. Conversation Coherence
- Decision: Inject the latest message metadata, sender info, and conversation history with every request.
- Benefits: LLM knows who is currently speaking (avoids sender confusion). LLM knows conversation history (maintains context coherence). LLM knows if it was @mentioned (decides whether to respond).
- Cost: Consumes ~3KB tokens per request. Conversation history may contain noise.
Components
Complete System Prompt Assembly Process
Summary of User-Controllable Layers
OpenClaw provides 3 types of user-controllable mechanisms:
- Layer 7 (Workspace Files) - Static configuration files. Scenario: Defining Agent identity, work specs, memory. Pros: Simple, intuitive, easy version control. Cons: Cannot adjust dynamically.
- Layer 8 (Bootstrap Hook System) - Dynamic injection scripts. Scenario: Injecting content based on context, executing commands, reading external files. Pros: Flexible, powerful, supports logic and commands. Cons: Requires learning the Hook system; script errors cause issues.
- Indirect Control of Layer 9 (Inbound Context) - Influencing context by sending messages. Scenario: Influencing LLM behavior via chat history or quoted messages. Pros: No config needed, natural interaction. Cons: Cannot precisely control.
Size Comparison Table
⚠️
Note: The following data are estimates; actual sizes vary by config and runtime context. Framework layers (Layer 1-6 + 9) should theoretically be the same but may vary slightly due to tool definitions, Skills loaded, etc.
Notes:
- Layer 7 and Layer 8 are user-controllable; sizes vary by Agent config.
- Other layers are auto-generated and theoretically identical across Agents.
- Actual measurements may differ due to tool availability, Skills loading, and runtime context.
Optimization Suggestions
- User-Controllable Part Optimization (Layer 7 + 8)
Since Layer 7 and 8 are user-controlled, here are optimization strategies:
Layer 7 (Static Files) Optimization:
✅ Recommended Lean Strategies:
- IDENTITY.md: Keep core TELOS framework, remove redundant descriptions, use tables instead of paragraphs.
- AGENTS.md: Use checklists instead of long paragraphs, show commands in code blocks, remove duplicate rule explanations.
- MEMORY.md: Rely on MemOS auto-export; don't add content manually—let the system maintain it.
❌ Practices to Avoid:
- Don't repeat descriptions the OpenClaw framework already knows.
- Don't copy detailed Skill descriptions into Workspace Files.
- Don't use excessive rhetoric or decorative language.
Layer 8 (Hook System) Optimization:
✅ Recommended Usage Strategies:
- Prioritize bootstrap-extra-files (simple scenarios).
- Use agent:bootstrap when conditional logic is needed (complex scenarios).
- Use before_prompt_build for real-time context (dynamic scenarios).
❌ Practices to Avoid:
- Don't execute time-consuming operations in Hooks (blocks System Prompt generation).
- Don't inject too much content in Hooks (exceeds token limits).
- Don't use unstable external dependencies in Hooks (causes startup failure).
- Prompt Pruning Strategy
If the System Prompt is too large, consider:
Conclusion
OpenClaw's System Prompt is not a single file, but a carefully orchestrated 9-layer architecture:
- Layer 1-6: Auto-generated by the framework, ensuring consistency and stability.
- Layer 7: User-editable static config files (IDENTITY.md, AGENTS.md, etc.).
- Layer 8: User-programmable dynamic injection scripts (Bootstrap Hook System).
- Layer 9: Real-time context automatically injected by the framework (Inbound Context).
There are 2 user-controllable layers (Layer 7 + 8), not just Layer 7 as previously misstated.
Understanding the differences and connections between these layers is key to mastering OpenClaw configuration.
