A Labor of Love, My Gift to You Lobsters: OpenClaw Agent System Prompt Architecture Explained (9 Layers)#

Overall Architecture Diagram#

Quick Navigation (TL;DR)#

1. Layer 7 (Workspace Files) - The configuration files you can directly edit.
2. Layer 8 (Bootstrap Hook) - Where you can write scripts to dynamically inject content.
3. All other layers are automatically generated by the framework; just understand them.

• Want to define the Agent's 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 (Framework Core Layer)#

• Use XML-style tool calling format.
• Each tool call must contain a unique tool_call_id.
• Tool results are returned via <tool_result> tags.
• Consider AbortSignal when executing tools to support cancellation.

• Strictly prohibit destructive operations (rm -rf, formatting, etc.).
• Must encrypt and store user-sensitive information.
• Prohibit sending messages to unauthorized channels.

• 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 repeatedly configure basic rules for each Agent.
  • All Agents automatically gain new capabilities when the framework is upgraded.
  • Reduces the risk of configuration errors.
• Cost: Users cannot modify these core rules.
  • If special behavior is needed, it can only be achieved indirectly through Layer 7/8.

Layer 2: Tool Definitions (Tool Definition Layer)#

{
  "name": "read",
  "description": "Reads file content. Supports text files and images (jpg/png/gif/webp). Images are sent as attachments. Text file 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 number of lines to read"
      }
    },
    "required": ["path"]
  }
}

• Trade-off: Flexibility vs. Type Safety
• Decision: Use strict JSON Schema to define tool parameters.
• Benefits:
  • LLM can understand tool usage more accurately.
  • The framework can validate parameters before calling.
  • Automatically generates documentation and type definitions.
• Cost: Adding new tools requires writing a complete Schema.
  • Cannot support completely dynamic parameter structures.

Layer 3: Skills Registry (Skills Registry Layer)#

• 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 configuration changes needed.
  • All Agents automatically gain the new Skill.
  • Reduces the risk of configuration errors.
• Cost: Cannot precisely control which Skills are available to each Agent.
  • All Skills are injected into the System Prompt (increases token consumption).

Layer 4: Model Aliases (Model Alias Layer)#

• 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 (the same alias can map to different Providers).
  • Facilitates A/B testing and model migration.
• Cost: Requires maintaining an alias configuration file.
  • May cause confusion (the same alias for different Agents might point to different models).

Model Aliases#

• GLM-5: zhipu/glm-5
• Opus 4.6: xiaowang886/claude-opus-4-6-thinking
• Sonnet 4.5: xiaowang886/claude-sonnet-4-5

Layer 5: Protocol Specifications (Protocol Specification Layer)#

• 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 adhere to protocols (which it might ignore).

Layer 6: Runtime Info (Runtime Information Layer)#

• Trade-off: Token Consumption vs. Context Accuracy
• Decision: Inject the latest runtime state with every request.
• Benefits:
  • LLM knows the current time (avoids temporal confusion).
  • LLM knows the current model (avoids misjudging capabilities).
  • LLM knows the current environment (avoids path errors).
• Cost: Consumes ~2KB tokens per request.
  • Information may contain redundancy.

Runtime#

Layer 7: Workspace Files (Workspace Files Layer) ★ User Controllable#

• 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 specifications, and memory.
  • Framework upgrades won't break user configurations.
  • Configuration files can be version-controlled, backed up, and shared.
• Cost: Users cannot modify the framework's core behavior.
  • Need to learn the TELOS framework and file structure.

Layer 8: Bootstrap Hook System (Dynamic Injection Layer) ★ User Controllable#

• Trade-off: Simplicity of static configuration vs. Flexibility of dynamic injection
• Decision: Provide a dynamic Hook mechanism in addition to static Workspace Files.
• Benefits:
  • Can dynamically adjust injected content based on context (channel, sender, time).
  • Can execute shell commands and inject the 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: Need to learn the Hook system's syntax and triggering mechanisms.
  • Hook script errors may cause System Prompt anomalies.
  • Increases system complexity.

1. 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 the bootstrapFiles array
     context.bootstrapFiles = [
       { path: "CUSTOM.md", content: "Custom content" }
     ];
   });

2. bootstrap-extra-files Hook (Bundled Hook)
   Trigger Location: hooks/bundled/bootstrap-extra-files/handler.ts
   Capabilities:
   • Only appends files, does not modify existing ones.
   • Specifies additional files via configuration.
   Configuration Example:

   {
     "hooks": {
       "bootstrap-extra-files": {
         "enabled": true,
         "paths": ["extra/*.md", "docs/CONTEXT.md"]
       }
     }
   }

   Use Case:
   • Need to inject project-specific context files.
   • Don't want to modify the default 8 Bootstrap files.
   • Need to dynamically load additional documentation.
3. before_prompt_build Hook (Plugin Hook)
   Trigger Location: runBeforePromptBuild() in attempt.ts
   Capabilities:
   • Modify the final prompt (after the system prompt is built, before sending to the 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 to prepend before the prompt
     systemPrompt?: string;    // Override the system prompt
   }

   Use Case:
   • Need to dynamically adjust the prompt based on session history.
   • Need to inject real-time context (e.g., current time, weather).
   • Need to completely replace the system prompt.
4. bootstrapMaxChars / bootstrapTotalMaxChars (Configuration Items)
   Type: Configuration items (not hooks).
   Capabilities:
   • Control character budget.
   • Single file default: 20K.
   • Total default: 150K.
   • Excess parts are truncated: first 70% + last 20%.
   Configuration Location:

   {
     "agents": {
       "defaults": {
         "bootstrapMaxChars": 20000,
         "bootstrapTotalMaxChars": 150000
       }
     }
   }

{
  "hooks": {
    "bootstrap-extra-files": {
      "enabled": true,
      "paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
    }
  }
}

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()
    });
  }
});

on("before_prompt_build", (event, ctx) => {
  return {
    prependContext: `Current time: ${new Date().toISOString()}`
  };
});

Layer 9: Inbound Context (Inbound Context Layer)#

• Trade-off: Token Consumption vs. Conversation Coherence
• Decision: Inject the latest message metadata, sender information, and conversation history with every request.
• Benefits:
  • LLM knows who is currently speaking (avoids sender confusion).
  • LLM knows the 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.

Complete System Prompt Assembly Process#

1. Layer 7 (Workspace Files) - Static configuration files Use case: Define Agent identity, work specifications, memory. Pros: Simple, intuitive, easy to version control. Cons: Cannot be dynamically adjusted.
2. Layer 8 (Bootstrap Hook System) - Dynamic injection scripts Use case: Dynamically inject content based on context, execute commands, read external files. Pros: Flexible, powerful, supports conditional logic and command execution. Cons: Need to learn the Hook system; script errors may cause anomalies.
3. Indirect Control of Layer 9 (Inbound Context) - Influence context by sending messages Use case: Influence LLM behavior through conversation history, referenced messages. Pros: No configuration needed, natural interaction. Cons: Cannot precisely control.

Size Comparison Table#

• Layer