About Openclaw Agent Definition

openclaw-agent-definition-overview.md

Openclaw Agent definition Overview

In openclaw, an "agent" is not defined as a rigid class or a database model. It is a dynamic and evolving "persona" constructed from a collection of Markdown (.md) files.

These files are combined at runtime to form a comprehensive "system prompt" that dictates the AI's identity, rules, and operational parameters.

The core components that collectively define the agent's persona include:

• AGENTS.md: Provides general behavioral guidelines, safety rules, and instructions for how the agent should use its tools.
• IDENTITY.md: Defines the AI's persona, including its name, role, and its relationship with the user.
• SOUL.md: Outlines the agent's core personality, values, and communication tone.
• USER.md: Stores information about the user, such as their work patterns, timezone, and communication style, allowing for personalized interactions.
• TOOLS.md: Lists the tools available to the agent and their configurations.
• HEARTBEAT.md: Contains a checklist of tasks for the agent to monitor and perform periodically, instructing it on how to interact with different applications.

The system-prompt assembly process in can be summarized as follows:

1. Modular Construction: The system.ts file functions as a builder or intelligent templating engine. It defines a structured layout for the overall system prompt, which is composed of numerous distinct sections.
2. Predefined Sections: The system prompt is organized into several fixed sections, each designed to convey specific information to the AI model. These sections include:
   • Tooling: Information about available tools and their descriptions (likely sourced from TOOLS.md).
   • Safety: Built-in guardrails and reminders for ethical behavior.
   • Skills: Instructions for loading and utilizing skills on demand.
   • OpenClaw Self-Update: Guidance for agent self-maintenance.
   • Workspace: Context about the agent's current working directory.
   • Documentation: Pointers to local documentation (e.g., AGENTS.md).
   • Workspace Files: This crucial section explicitly includes the content of "bootstrap files" such as USER.md, IDENTITY.md, and SOUL.md directly into the prompt.
   • Sandbox: Details about the execution environment.
   • Current Date & Time: Real-time contextual information.
   • Reply Tags: Provider-specific syntax for responses.
   • Heartbeats: Details related to periodic prompts and acknowledgments (likely from HEARTBEAT.md ).
   • Runtime: Host, OS, Node.js version, and other execution environment specifics.
   • Reasoning: Current visibility and hints for reasoning toggling.
3. Dynamic Inclusion: The content from the Markdown files is dynamically fetched and inserted into their respective sections within this structured prompt. This allows the system to present a cohesive yet customizable initial context to the LLM.
4. Prompt Modes: system.ts supports different "prompt modes" (e.g., full, minimal, none). These modes enable conditional assembly, allowing certain sections (like Skills, Memory Recall, or User Identity) to be omitted to create more compact prompts, especially for sub-agents or specific tasks.
5. Runtime Contextualization: Beyond the static Markdown files, system.ts also integrates dynamic runtime information, such as the current date and time, sandbox details, and host environment specifics, to provide the AI with a complete operational context.

System Prompt Handling

This section summarizes the parsing logic, master template structure, and the role of prompt modes in assembling the system prompt within the openclaw codebase, based on analysis of src/agents/system-prompt.ts and src/agents/workspace.ts from the v2026.2.6 release.

I. Parsing Logic and File Assembly

The core logic for constructing the system prompt, including the integration of Markdown (.md) files, is encapsulated within the buildAgentSystemPrompt function located in src/agents/system-prompt.ts. The processing of Markdown files follows a distinct two-step process:

1. File Loading (src/agents/workspace.ts):

   • The loadWorkspaceBootstrapFiles function is responsible for reading the content of specific .md files (such as AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md, and memory.md) from the agent's designated workspace directory.
   • It utilizes standard Node.js fs.readFile to asynchronously read the full textual content of each file.
   • Front Matter Stripping: A crucial preprocessing step involves the stripFrontMatter utility. This function removes any YAML front matter (blocks delimited by ---) found at the beginning of the Markdown files. This ensures that only the relevant instructional or informational content, and not metadata, is included in the system prompt.
   • The loaded files are returned as an array of WorkspaceBootstrapFile objects, each containing the file's name, its full path, and its processed content.
   • Subagent Context Filtering: The filterBootstrapFilesForSession function provides a mechanism to limit the bootstrap files provided to subagents. For subagent sessions, only AGENTS.md and TOOLS.md are passed on, effectively reducing the context.

2. Context Injection (src/agents/system-prompt.ts):

   • The array of contextFiles (which are the pre-processed .md files) is passed as a parameter to the buildAgentSystemPrompt function.
   • Within this function, if contextFiles are provided, their content is directly injected into a dedicated section of the system prompt labeled "# Project Context".
   • Each individual file's content is prefaced with its own Markdown subheading: ## ${file.path}, explicitly indicating its origin, followed by its content.
   • Special Handling for SOUL.md: The system specifically checks for the presence of SOUL.md within the contextFiles. If found, a dedicated guidance instruction is added to the system prompt: "If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it."

In summary, the "parsing" of Markdown files is primarily a direct read and inclusion of their textual content, with an initial front matter stripping step. Their role is to provide modular content blocks that are programmatically inserted into the larger system prompt structure.

II. Master Template Structure

The buildAgentSystemPrompt function in src/agents/system-prompt.ts serves as the master template for generating the openclaw system prompt. It is a TypeScript function that constructs the prompt as a single, multi-line string by programmatically concatenating various Markdown-formatted sections.

The template is highly structured, typically starting with a fixed introductory statement and then dynamically assembling numerous sections, each introduced by a Markdown H2 heading (## Section Title). The presence and content of these sections depend on the parameters passed to buildAgentSystemPrompt and the active promptMode.

Key sections that can be included in the master template are:

• Introductory Line: "You are a personal assistant running inside OpenClaw."
• ## Tooling: Details about available tools.
• ## Tool Call Style: Guidance on how to use tools.
• ## Safety: Core safety guardrails and principles.
• ## OpenClaw CLI Quick Reference: Commands for managing OpenClaw.
• ## Skills (mandatory): Guidance on skill usage (if skillsPrompt is provided).
• ## Memory Recall: Instructions for using memory tools (if memory_search or memory_get tools are available).
• ## OpenClaw Self-Update: Guidance for self-maintenance (if gateway tool is available and not in minimal mode).
• ## Model Aliases: Information on model aliases (if provided and not in minimal mode).
• ## Current Date & Time: User's timezone (if provided).
• ## Workspace: Agent's working directory and notes.
• ## Documentation: Pointers to openclaw documentation.
• ## Sandbox: Details about sandboxed execution environment.
• ## User Identity: Owner numbers (if provided and not in minimal mode).
• ## Workspace Files (injected): An introductory note for the injected Markdown files.
• # Project Context: Contains the injected content from contextFiles (i.e., the Markdown files), each with its own ## FILENAME.md subheading.
• ## Reply Tags: Guidance on using reply tags (if not in minimal mode).
• ## Messaging: Details about messaging capabilities and the message tool (if not in minimal mode).
• ## Voice (TTS): Text-to-speech hints (if provided and not in minimal mode).
• ## Subagent Context / ## Group Chat Context: Extra system prompt content, with heading changing based on promptMode.
• ## Reactions: Guidance on using reactions (if reactionGuidance is provided).
• ## Reasoning Format: Hints on thinking and final tags (if reasoningTagHint is true).
• ## Silent Replies: Instructions for silent replies (if not in minimal mode).
• ## Heartbeats: Guidance on heartbeat mechanism (if not in minimal mode).
• ## Runtime: Dynamic information about the current runtime environment.

III. Prompt Modes and Section Inclusion/Exclusion

The promptMode parameter, which can be "full", "minimal", or "none", explicitly dictates which sections of the master template are included in the final system prompt. This provides a flexible mechanism to tailor the agent's context based on its role or the operational environment. The isMinimal boolean flag (promptMode === "minimal" || promptMode === "none") is used throughout buildAgentSystemPrompt to control conditional rendering.

1. PromptMode: "none":

   • This is the most restrictive mode.
   • Exclusion: Virtually all sections are excluded.
   • Inclusion: The function returns only a single, basic introductory line: "You are a personal assistant running inside OpenClaw."

2. PromptMode: "minimal":

   • This mode is designed for scenarios requiring a reduced context, such as subagents.
   • Excluded Sections: Explicitly omits a significant number of "extended" sections, including:
     • ## User Identity
     • ## Skills (mandatory)
     • ## Memory Recall
     • ## Documentation
     • ## Reply Tags
     • ## Messaging
     • ## Voice (TTS)
     • ## Silent Replies
     • ## Heartbeats
     • ## Model Aliases
     • ## OpenClaw Self-Update (even if the gateway tool is available, it's suppressed in minimal mode).
   • Included Sections: Focuses on essential operational context:
     • ## Tooling
     • ## Tool Call Style
     • ## Safety
     • ## OpenClaw CLI Quick Reference
     • ## Workspace
     • ## Sandbox (if enabled)
     • ## Workspace Files (injected) and # Project Context (if contextFiles are provided).
     • ## Runtime
     • ## Subagent Context (If extraSystemPrompt is provided, this heading is used instead of ## Group Chat Context).
     • ## Reactions (if reactionGuidance is provided).
     • ## Reasoning Format (if reasoningTagHint is true).

3. PromptMode: "full" (Default):

   • This is the most permissive mode, intended for main agents.
   • Inclusion: All applicable sections are considered for inclusion based on the specific parameters provided to buildAgentSystemPrompt. This means that if the necessary data is present (e.g., ownerNumbers, skillsPrompt, docsPath), the corresponding sections will be rendered in the system prompt. This mode provides the richest context to the AI model.

This structured and conditional assembly process ensures that the OpenClaw agent receives a highly tailored and relevant system prompt for its given context and role.