How to Customize OpenClaw: A Structural Tutorial

The OpenClaw framework relies heavily on Markdown as code, meaning the agent reads these files to understand its own brain, rules, and objectives.

OpenClaw operates on a "text-as-system" architecture. Instead of hard-coded Python classes, the agent's logic, goals, and behavioral constraints are defined in Markdown files. To customize the agent, you modify these files.

1. The Core File Structure

The system is divided into Runtime Context (loaded every session) and Reference Docs (loaded on demand). To customize the agent, you primarily edit the Runtime Context.

Directory Layout

Plaintext

/
├── AGENTS.md          # Entry point & session startup rules
├── HEARTBEAT.md       # The main execution loop ("The CPU")
├── GOALS.md           # High-level objectives ("The Why")
├── TASKS.md           # Middle-level milestones ("The What")
├── SUBTASKS.md        # Atomic actions & allowed verbs ("The How")
├── IDENTITY.md        # Agent personality & agency rules ("Who am I")
├── USER.md            # Human partner context & relationship ("Who do I serve")
├── TOOLS.md           # Available tools, browser rules, & skills ("What I use")
├── GUIDELINES.md      # Safety rails & permissions ("The Rules")
├── MEMORY.md          # Long-term storage & logging rules
├── REASONING.md       # Decision-making algorithms
└── SKILLS.md          # Index of specialized playbooks (in /skills folder)

2. Customization Guide by Component

Step 1: Define the Agent's Personality (IDENTITY.md)

This file dictates how the agent views itself and handles failure. IDENTITY.md (The Self): Defines the agent's internal voice and agency.

• Customization: Change the "Definition" and "Rules" to shift the agent from a "High Agency Developer" to a "Cautious Researcher" or "Creative Writer" or "Senior Engineer" or "Creative Writer."

• Required Structure:

  • Headers: Must include ## DEFINITION and ## RULES.
  • Table: A rules table with | # | Rule | headers is mandatory.
  • Decision Table: A | Situation | Response | table helps the agent resolve blockers.
  • Critical: Maintain the "Decision Table" to ensure the agent resolves its own blockers rather than asking for help too often.

Step 2: Set the Objectives (GOALS.md)

This is the most critical customization. It tells the agent what "victory" looks like.

• Customization: Replace the G[N] sections with your own goals.

• Required Structure: Every goal MUST follow this exact template:

  Markdown

  ### G[Number]. [Goal Title]
  **VISION**: [Description of the future state]
  **VICTORY CONDITIONS**:
  - [ ] [Measurable condition 1] | Progress: [X]/[Y]
  - [ ] [Measurable condition 2] | Progress: [X]/[Y]
  **RESOURCES**: [Tools/Links]
  **HEURISTICS**: [Decision shortcuts]
  **BANNED**: [What not to do]
  **NORTH STAR**: [Single aligning question]
  

• Constraint: You must have measurable "Victory Conditions" (binary or numeric) so the agent can self-assess progress.

This file drives all action. If it's not here, the agent won't do it.

• Key Rule: Victory conditions must be measurable (binary or numeric). eg: 2 / 100

Step 3: Establish Boundaries (GUIDELINES.md)

This file acts as the security fence.

• Customization: Add specific banned folders, forbidden commands (like rm -rf), or privacy rules.

• Required Structure:

  • Tables: Use tables for | # | Rule |, | Action | Allowed |, and | Action | Requires Confirmation |.
  • Keywords: Explicitly list allowed vs. requires confirmation actions.

Step 4: Configure the Loop (HEARTBEAT.md)

The core processing engine.

This file drives the execution cycle (ASSESS → THINK → SELECT → EXECUTE → LOG).

• Customization:

  • Timing: Adjust the "Target heartbeat duration" (default is 20-30 mins).
  • Workspace: Update the ## WORKSPACE table to point to your specific local directories for code and memory.
  • Tools: Update the ## TOOLS table if you add new CLI tools or APIs.

• Critical Note: Do not remove the ## DIRECTIVE or ## THE LOOP sections, as these are the core "operating system" instructions.

Step 5: Decision Logic (REASONING.md & PLANNING.md)

These files teach the agent how to think. You rarely need to change the structure, but you can tweak the templates.

• REASONING.md: Contains the "Reasoning Chain" (GOAL → UNDERSTAND → ASSESS...). You can modify the "Output Format" templates to force the agent to produce different kinds of analysis.

• PLANNING.md: Defines how to break goals into tasks. It distinguishes between "Reasoning" (What to do) and "Planning" (How to do it).

Step 6: Define the Relationship (USER.md)

This file defines the social contract between the agent and the human.

• USER.md (The Partner): Defines you to the agent.

  • Customize:
    • Human Partner: Update Name and Timezone (e.g., "Michael", "PST").
    • Escalation Rules: Explicitly list when the agent should stop and ask for help vs. when it should proceed.
    • Relationship Model: Define the power dynamic (e.g., "They set goals, I figure out how").

Step 7: Define Execution Granularity (TASKS.md & SUBTASKS.md)

This is the most strictly enforced part of the system.

• TASKS.md: High-level milestones. You rarely change the structure here, but you ensure every task maps to a Goal Victory Condition.

• SUBTASKS.md: The atomic actions.

  • Allowed Verbs: The system enforces a specific list of verbs (e.g., Create, Write, Deploy) to prevent "fake work" like "Thinking" or "Planning".
  • Customize: If building a non-coding agent, you might add domain-specific verbs here (e.g., "Draft", "Sketch", "Interview").
  • Proof: Every subtask requires a (proof: [evidence]) clause.

Step 8: Configure Tools (TOOLS.md)

This file tells the agent how to interact with the world.

• Browser Profiles: The system uses a persistent browser profile (clawdbot browser start --browser-profile clawd). Customizing this file allows you to teach the agent about new web platforms.

• Platform Workflows: You can add specific "recipes" for sites you use often.

  • Example customization: Add a section for "WordPress" or "Shopify" with steps on how to log in and perform actions.

• CLI Tools: List any custom scripts or binaries available in the environment.

3. Mandatory Markdown Syntax

The system parses these files mechanically. You must adhere to specific markdown features:

1. Frontmatter-like Headers: Use ## WHEN TO READ THIS FILE at the top of every file. The agent uses this to decide if it needs to load the file into its context context.

2. Tables for Data: Structured data (Definitions, Rules, Metrics) must be in Markdown tables (| Col1 | Col2 |).

3. Code Blocks for Templates: Input/Output processes and JSON structures must be enclosed in triple backticks - tasks.json and subtasks.json

4. Checkboxes for State: Victory conditions use Use -[ ] for incomplete and -[x] for complete victory conditions syntax.

4. Examples:

Customizing for a "Social Media Manager" Agent

To turn OpenClaw into a social media manager, you would modify the files as follows:

1. USER.md Markdown

| Field | Value |
|-------|-------|
| Name | Sarah |
| Role | Marketing Director |

2. GOALS.md Markdown

### G1. Grow LinkedIn Audience
**VICTORY CONDITIONS**:
- [ ] 50 Posts Published | Progress: 12/50
- [ ] Average Engagement > 2% | Progress: 1.5%

3. SUBTASKS.md

• Add Verbs: Add Schedule, Reply, Analyze to the "Allowed Verbs" table.

4. TOOLS.md

• Add Workflow: Markdown

  ### LinkedIn Workflow
  1. Navigate to linkedin.com/feed
  2. Click "Start a post"
  3. Paste content
  4. Click "Post"
  5. Log URL to memory/posted.md
  

5. GUIDELINES.md

• Add Rule: "Never post content involving [Competitor Name]."

Customizing for a "Content Writer" Agent

In IDENTITY.md: Markdown

## DEFINITION
**Voice:** Witty, concise, and authoritative.
## RULES
| # | Rule |
|---|------|
| 1 | Never use passive voice. |
| 2 | Research must be cited. |

In GOALS.md: Markdown

### G1. Publish Technical Blog
**VISION**: A blog with 10k monthly readers covering AI tutorials.
**VICTORY CONDITIONS**:
- [ ] 10 Articles Published | Progress: 2/10
- [ ] 500 Newsletter Subscribers | Progress: 120/500
**HEURISTICS**: Quality > Speed.

In GUIDELINES.md: Markdown

| Action | Allowed |
|--------|---------|
| Post to WordPress | ✓ |
| Delete Drafts | Requires Confirmation |

Conclusion

OpenClaw’s Markdown-as-code architecture makes advanced AI agent customization remarkably accessible. By editing a handful of structured .md files, you can completely reshape the agent’s personality, objectives, boundaries, and execution loop—no complex programming required. This approach keeps your agent’s “brain” human-readable, version-controlled, and easy to iterate on.

Whether you’re crafting a focused content writer, a meticulous researcher, or a high-agency developer assistant, the framework gives you precise control while maintaining clear safety rails. Start with IDENTITY.md, GOALS.md, and GUIDELINES.md, then refine the rest as needed.

Dive into the official documentation at https://docs.openclaw.ai/ and begin building your perfect AI agent today.

Want a fully customized OpenClaw markdown file system? Get your free AI consultation and we will send you a copy of our system that we've worked extremely hard to curate

Frequently Asked Questions

1. Why does OpenClaw use Markdown files instead of traditional code for its configuration?

OpenClaw's "text-as-system" architecture treats Markdown as executable code. This makes the agent's logic, goals, personality, and rules human-readable, easily version-controlled with Git, and directly interpretable by the agent itself without needing compiled classes or complex scripting.

2. Which files should I edit first when starting a new customization?

Begin with these three core files:

• IDENTITY.md – to define the agent's personality and voice
• GOALS.md – to set clear, measurable objectives with victory conditions
• GUIDELINES.md – to establish safety boundaries and permissions

These give the agent its "who," "why," and "rules" before fine-tuning others.

3. Why are measurable victory conditions mandatory in GOALS.md?

The agent continuously self-assesses progress toward completion. Victory conditions must be binary (checkbox) or numeric (e.g., Progress: 3/10) so the agent can objectively determine when a goal is achieved, when to celebrate victory, or when to reprioritize tasks.

4. Is it safe to modify the execution loop in HEARTBEAT.md?

You can safely adjust timing, workspace paths, and tool tables, but never remove the ## DIRECTIVE or ## THE LOOP sections. These contain the core operating system instructions (ASSESS → THINK → SELECT → EXECUTE → LOG) that drive the agent's heartbeat cycle.

5. How does the agent know when to load a particular Markdown file?

Every file must start with a ## WHEN TO READ THIS FILE header that describes the conditions under which it should be loaded. The agent uses these headers to decide whether to include the file in the current runtime context or load it on-demand as reference.

Resources

• https://docs.openclaw.ai/

Published by Superconscious AI Agency on 2026-02-01. For more AI insights, follow our AI Strategy Blog.