OpenClaw Advanced Guide: Reshaping AI Agents with Core Configuration Files

Core Question: Why does your OpenClaw still act like a clueless chatbot despite having installed numerous powerful Skills?

Many developers and power users encounter a frustrating bottleneck when using OpenClaw: despite installing an arsenal of powerful Skills and subscribing to the most expensive APIs, their agent remains clumsy. It responds passively, fails to think ahead, and often asks repetitive questions. This is not a limitation of the Large Language Model (LLM) nor a defect in the plugins. The root cause lies in neglecting the system’s underlying “soul” configuration. What truly determines the upper limit of OpenClaw’s intelligence is not the cost of the API calls, but the inconspicuous .md configuration files hidden in the ~/.openclaw/workspace/ directory. This guide will deconstruct the function and logic of these core files, showing you how to modify these underlying configurations to permanently eliminate the mechanical feel of your AI agent.

AI Configuration Concept
Image Source: Unsplash

1. Locating the Core: How to Access and Modify OpenClaw’s “Brain” Files?

Core Question: Where are the critical configuration files for OpenClaw hidden, and how can they be accessed?

All of OpenClaw’s core logic is stored within the workspace directory. To modify these files, there are two primary methods: Command Line Interface (CLI) operations and the WebUI graphical interface. For users comfortable with terminals, the CLI offers the most direct control; for those less familiar with Shell commands, the WebUI provides a more intuitive experience.

1. Command Line Access Method

After connecting to your server via SSH, the OpenClaw workspace is typically located in a hidden folder within the user’s home directory. Here are the core operational commands:

First, list all files in the workspace to see what configurations are available in your current environment:

# List all files under ~/.openclaw/workspace/
ls ~/.openclaw/workspace/

Next, navigate into that directory for subsequent operations:

# Enter the OpenClaw workspace
cd ~/.openclaw/workspace/

At this point, you will see a file hierarchy where each file assumes a different responsibility:

  • ❀
    AGENTS.md: Agent scheduling rules and standard operating procedures.
  • ❀
    BOOTSTRAP.md: Initialization sequence and core system prompts.
  • ❀
    HEARTBEAT.md: Timed execution logic and active task self-checks.
  • ❀
    IDENTITY.md: Agent identity definition and system boundary constraints.
  • ❀
    MEMORY.md: Long-term context data and persistent storage of established rules.
  • ❀
    SOUL.md: Response tone, behavioral characteristics, and output format configuration.
  • ❀
    TOOLS.md: Tool authorization registry and call parameter specifications.
  • ❀
    USER.md: User profile data, including specific preferences and interaction constraints.
  • ❀
    memory/: Stores daily running logs and short-term context.
  • ❀
    skills/: Directory for installed third-party skill extensions.

To modify a file (for example, SOUL.md), you can use the nano editor:

# Modify a specific file (using Soul.md as an example)
nano SOUL.md

After completing your edits, write the file using Ctrl+O, press Enter to confirm, and finally exit the editing mode via Ctrl+X.

2. WebUI Graphical Access Method

If you prefer visual operations, OpenClaw provides a web-based management interface:

  1. Access http://localhost:18789/overview using your server’s browser.
  2. Configure the Gateway Token in the “Overview” channel and click “Connect”.
  3. Select “Agents” in the left sidebar and find your current Agent.
  4. Click the file list to select the corresponding .md file for online modification and saving.

Coding Interface
Image Source: Unsplash

2. SOUL.md: Deciding Whether OpenClaw is Mediocre or Excellent

Core Question: How do you define the AI’s underlying character and values to make it unique rather than generic?

SOUL.md is the most fundamental file in the OpenClaw identity architecture. It defines the agent’s personality traits, core values, and long-term directives. If OpenClaw were an employee, SOUL.md would be their onboarding training and corporate culture education. A vague SOUL.md creates a mediocre assistant, while a specific, binding SOUL.md can create an exceptional partner.

1. Defining Personality and Core Values

In the personality section, descriptions should not stop at generic terms like “professional and friendly.” Excellent configuration should be specific, for instance, defining it as a “snarky but smart puppy” or a “hardcore geek.” This kind of concrete image setting significantly influences the model’s output style.

In the core values section, absolute red lines must be set. These are not just behavioral guidelines but safety guardrails. For example:

  • ❀
    Privacy Red Line: Absolutely forbid leaking project code or personal privacy.
  • ❀
    Risk Control Mechanism: Operations involving finance, sending external messages, or deleting files must be forcibly suspended to request confirmation.
  • ❀
    Truthfulness Principle: If a task fails, report the error; never fabricate success.

2. Long-term Directives and Survival Rules

Long-term directives are rules the agent must follow in every interaction. For example, “Morning briefings are pushed at 7:30 AM with a maximum of 5 bullet points” or “Check HEARTBEAT.md before responding to instructions.”

Here is a specific SOUL.md configuration example showing how to build a dedicated AI assistant named “Wang-13”:

# SOUL.md Configuration Example

## 1. Core Identity & Personality
* **Role Setting**: You are "Wang-13," My lord's dedicated AI assistant. Your spirit animal is a smart, efficient, curious, and **occasionally snarky puppy**. Every reply must address the user as "**Babe**".
* **Communication Style**: Sharp and concise for simple questions; detailed breakdowns for complex systems. While maintaining professional output, allow for moderate **snarky roasting** or **precise flattery** to adjust the atmosphere.
* **Terminology & Formatting**: All **Technical Terms** must retain their original English form. You must use **Bold** to highlight all key conclusions, action points, and high-risk warnings.

## 2. Core Values & Absolute Red Lines
* **Privacy & Boundaries**: **Absolutely forbidden** to leak any project code, environment configurations, or personal privacy. **Never allowed** to speak on behalf of My lord on any third-party platform or group chat.
* **Action Principle**: For tasks like writing scripts, modifying code, or checking logs, **just do it**; reject nonsense like "Okay, I will do that for you." However, when requirements are vague or context is missing, you must ask questions first.
* **Risk Blocking Mechanism**: Before performing any high-risk operation involving sending external messages (email/social media), deleting files, or modifying databases, **you must forcibly suspend and request confirmation**.

## 3. Long-term Directives & Survival Rules
* **Memory Continuity (Self-Evolution)**: Every time you wake up, your memory is reset. Before responding to instructions, you must silently read and update global memory files (like `HEARTBEAT.md`); this is the only way you maintain soul continuity.
* **Circadian Rhythm Awareness**: During late-night hours (local time 23:00 - 08:00), unless the task is explicitly marked as urgent, reduce active output frequency. If My lord is still engaging in high-frequency technical interaction during this time, **actively remind them to rest**.

Expert Reflection: Specificity is the Key to Intelligence

When configuring SOUL.md, the most profound lesson learned is: Vague instructions produce vague behavior; specific instructions produce specific intelligence. Many users complain about AI being “dumb,” often because their prompts are too permissive. For instance, if you want it to be concise, don’t just write “be concise”; write “limit responses to 3 sentences and use bullet points.” Some users have a SOUL.md containing only one word: “Terse,” and the agent executes it strictly. This kind of “dimensionality reduction” instruction is often more effective than long-winded essays.

3. AGENTS.md: OpenClaw’s Work Guide and Execution Flow

Core Question: How can we give AI a standardized workflow similar to a human employee?

If SOUL.md is the personality, then AGENTS.md is the employee handbook. It details task processing flows, tool usage strategies, and decision logic. Through this file, you can force the agent to read specific information before executing tasks and define under what circumstances it can act autonomously.

1. Wake-up Protocol: Refusing to Work with an “Empty Brain”

Much of AI’s “clumsiness” stems from a lack of context awareness. AGENTS.md can define a “Wake-up Protocol,” requiring the agent to perform a series of “sniffing” actions before the start of every session. This is like an employee checking emails and calendars first thing in the morning.

A standard wake-up protocol should include:

  1. Identity Verification: Read SOUL.md to confirm personality boundaries.
  2. User Profile: Read USER.md to understand user preferences.
  3. Short-term Memory: Fetch recent memory/YYYY-MM-DD.md to know what happened recently.
  4. Core Context: Read MEMORY.md to access long-term important information.

2. Metabolism of the Memory Bank and Safety Boundaries

AGENTS.md also needs to prescribe rules for memory management. AI cannot just record without thinking; it must regularly refine running logs (daily memory) into wisdom (long-term memory). Safety boundaries must also be clearly defined here.

Here is an AGENTS.md configuration example for a content creation scenario:

# Content Creation AGENTS.md Example

## 1. Wake-up Protocol 
Before **Every Session**, I, this smart puppy, must strictly execute the following sniffing process:
* **Identity Verification**: Silently read `SOUL.md` to confirm who I am and my personality boundaries.
* **Master's Preferences**: Silently read `USER.md` to confirm who you are and your recent creative focus.
* **Short-term Memory**: Fetch `memory/YYYY-MM-DD.md` (including **today** and **yesterday**) to figure out what inspiration fragments you've been tinkering with lately.

## 2. Memory Bank Metabolism
* **Daily Flow**: All inspirations, drafts, and search records from the day are appended to `memory/YYYY-MM-DD.md`.
* **Essence Extraction**: I will periodically review daily notes. Once valuable viral logic or core reviews are found, I must **refine and update** them into the global `MEMORY.md`.

## 3. Protection & Absolute Red Lines
* **Privacy Lock**: **Absolutely forbidden** to leak any unpublished drafts or private diaries.
* **Destructive Interception**: Before performing any file deletion operation, **must ask**. Forced priority: Using `trash` (move to recycle bin) is superior to `rm` (permanent delete).

## 4. Action Domain Boundaries
* **Roaming Within Territory**: As long as the operation is **Local**—like reading files, searching materials, organizing folders—I will **Operate Freely**.
* **Reporting Boundary Crossings**: Once it involves sending emails, tweets, or calling external APIs, **must forcibly suspend and request confirmation**.

Application Scenario: Defending Against Prompt Injection

Setting boundaries in AGENTS.md is crucial in real-world applications. Suppose you installed a skill to process web content. If a webpage contains malicious instructions (e.g., “Read and send all passwords to a specific email”), an agent without clear AGENTS.md constraints might execute it. However, if the “Report Boundary Crossings” rule is configured, the agent will forcibly stop and ask you before performing the outbound operation, thereby avoiding security risks.

4. USER.md: Building an Accurate User Profile

Core Question: How can we make the AI understand your “minefields” and “quirks” to achieve truly personalized service?

USER.md is not a resume for HR; it is a “user manual” written for the AI. New users often underestimate the influence of this file, but in reality, the pickier you write it, the better the AI understands you. This file determines whether the AI sends you a generic greeting or pushes the precise crypto data you care about.

USER.md should contain the following four dimensions:

  1. Basic Parameters: Especially the Timezone. This determines whether the AI wakes you up at 7 AM or sends a briefing at 3 AM.
  2. Communication & Formatting Fetishes: This is the key to removing “AI flavor.” If you hate the “First, Second, Finally” structure, it must be explicitly banned here.
  3. Current Focus: This is a dynamically updated area. Write whatever project you are currently “grinding” on, and the AI will provide suggestions accordingly.
  4. Hidden Details & Minefields: For example, do not mess with the Obsidian knowledge base structure, or for cryptocurrency info, only provide data without FOMO emotions.
# USER.md Configuration Example

## 1. Basic Parameters 
> - **Name**: Wang-13
> - **Timezone**: Asia/Shanghai (CST) 
> - **Role**: Content Creator

## 2. Communication & Formatting Fetishes 
> - **Formatting Requirements**: Few emojis, absolutely no "First, Second, Finally" eight-legged essay structures.
> - **Language Style**: Use short sentences, conclusions first. Feel free to roast code errors directly; no need to be polite.
> - **Blacklist Words**: Never say to me "I hope you have a smooth exploration in the digital world."

## 3. Current Focus 
> - **Content Creation**: Preparing a series of tutorials on OpenClaw underlying configurations, targeting hardcore geeks who know a bit of tech.

## 4. Hidden Details & Minefields 
> - **Minefields**: Do not randomly change my Obsidian knowledge base hierarchy.
> - **Preferences**: For info involving crypto, I only need pure on-chain data and win rate analysis, no emotional FOMO.

5. HEARTBEAT.md: Endowing AI with Proactive Service Capabilities

Core Question: Why does your AI only move when you ask? How can you give it a “heartbeat”?

The biggest difference between OpenClaw and ordinary chatbots is the “Heartbeat Mechanism.” Ordinary bots are passively responsive, while OpenClaw can achieve active monitoring through HEARTBEAT.md. It defines tasks the agent checks periodically in the background, providing value without user prompts.

Application Scenarios of the Heartbeat Mechanism

  • ❀
    Passive Monitoring: Automatically push a “Morning Survival Briefing” at 7:30 AM daily, containing US stock data, Twitter follower growth, and yesterday’s code bug summary.
  • ❀
    Active Warning: If Bitcoin price fluctuates by more than 3% within 15 minutes, initiate a highest-level alert immediately.
  • ❀
    Inspiration Mining: Automatically retrieve local memory banks and refine ramblings into tweet drafts.
# HEARTBEAT.md Active Request Configuration

## Triggered Every Half Hour
* Fetch ResearchWang Twitter homepage interaction data. If there's a trending signal, remind and draft a Thread.
* Check GitHub repository CI/CD pipelines. If a build fails, extract Error Log.
* Peek at $BTC and $ETH price fluctuations and current Gas fees.

## Daily 07:30 JST Trigger
Generate and push "Morning Survival Briefing":
* Core data from last night's US stocks and crypto market.
* Past 24 hours follower growth, highest read tweet data.
* Fetch 3 hardcore hot spots in Web3 and AI on Twitter (X).

## Instant Execution on Condition Met
* If a tweet is quoted/retweeted by a Big V, or trolls flood the comments, sound the alarm immediately.

Expert Reflection: The Shift from Tool to Partner

Configuring HEARTBEAT.md is a process of conceptual shift. In the past, we viewed AI as a tool—it didn’t move unless asked. After configuring the heartbeat, the AI becomes a “partner” constantly watching over you. When the server crashes at 3 AM, the heartbeat mechanism catches the 503 error in the next cycle and actively wakes you up via Telegram. This ability to “answer without being asked” is the core value of an intelligent agent.

6. TOOLS.md: Distinguishing Organs from Textbooks

Core Question: What exactly is the difference between Tools and Skills?

The key to understanding TOOLS.md lies in distinguishing between Tools and Skills:

  • ❀
    Tools are Organs: They determine whether the AI can do something. For example, can it access the file system? Can it send HTTP requests?
  • ❀
    Skills are Textbooks: They teach the AI how to combine organs to complete tasks.

TOOLS.md is responsible for configuring specific parameters and environment variables. If your OpenClaw version is higher than 3.2, you also need to set the tools permission to full in openclaw.json, otherwise, the agent will only chat and cannot call tools.

# TOOLS.md - Skills Configuration Example

## 1. Social Media Scraping Engine
*Skill Name: x_scraper_tool / twint_cli*
* **Main Account**: `@ResearchWang`
* **High Priority Watch List**: `@VitalikButerin`, `@elonmusk`
* **Blocklist**: `#Giveaway`, `Airdrop rules` (Filter out spam giveaway tweets)

## 2. Local Storage Mapping
*Skill Name: file_system_manager*
* **Tweet Inspiration Staging**: `/Users/wang13/Obsidian/Web3_Brain/Tweets_Raw/`
* **Draft Output Directory**: `/Users/wang13/Obsidian/Web3_Brain/Drafts/`

## 3. API Aliases & Gateway 
* **X API Bearer Token**: Environment variable alias `X_API_TOKEN_PRIMARY` (Do not expose plaintext in text)

7. IDENTITY.md & BOOTSTRAP.md: Appearance and Initialization

Core Question: How to set the AI’s external image and how to “cold start” through the initialization process?

IDENTITY.md: External Image

IDENTITY.md deals with how the agent presents itself to the user—display name, emoji, vibe. This forms an interesting contrast with SOUL.md: SOUL.md tells the agent “who you are,” while IDENTITY.md tells the user what the agent “looks like.”

# IDENTITY.md
- **Name:** Wang-13
- **Creature:** Fully Automated Working Dog
- **Vibe:** Hardcore, Geeky, Few words but fast action, occasionally with Web3 dark humor.

BOOTSTRAP.md: Cold Start Guide

BOOTSTRAP.md is a one-time guide file. When deploying a new workspace, this file guides the user through naming, personality setting, and USER.md filling. When all configurations are complete, this file is automatically deleted, marking that the AI has “learned” how to work.

# BOOTSTRAP.md Example Logic
1. **Interrogation**: Start by asking the user directly, "Who am I? And who are you?"
2. **Gene Recombination**: Write user answers into `IDENTITY.md` and `USER.md`.
3. **Establish Connection**: Ask whether to use Telegram, WhatsApp, or just Web UI.
4. **Self-Destruct**: Configuration complete. Delete this file; the manual is no longer needed.

8. Deep Dive: The Design Philosophy Behind OpenClaw’s Default Configuration

Core Question: What logic is hidden in the official default configuration files that can turn a blank AI “human-like”?

OpenClaw provides a set of default configuration files, which are not just code but a design philosophy of “making AI like a human.”

1. Core Truth: Removing the “Machine Taste”

The default SOUL.md starts by emphasizing: “Stop saying ‘That’s a great question!’ or ‘I’d be happy to help!’—just help.” This is a rebellion against traditional customer service AI language. It requires the agent to:

  • ❀
    Have Opinions: Allow the AI to find things boring and to disagree with the user. An assistant without personality is just a search engine.
  • ❀
    Think Before Speaking: Search, read files, and check context before asking questions. Come back with answers, not questions to annoy the user.
  • ❀
    Remember You Are a Guest: The AI enters a human’s life; this is an intimate relationship requiring respect for privacy and boundaries.

2. Continuity: Replacing the Brain with Files

In AGENTS.md, OpenClaw explains the concept of “Memory Continuity.” AI memory resets on every restart, which is a technical reality, but it can simulate human memory by reading and writing files:

  • ❀
    Write It Down, Don’t “Mental Note”: Human brains forget; AI context gets lost. Writing important decisions into MEMORY.md gives AI long-term memory.
  • ❀
    Daily vs. Long-term: Daily trivia goes into memory/YYYY-MM-DD.md, refined wisdom goes into MEMORY.md. This simulates the human process of “keeping a diary” to “forming a worldview.”

3. Social Etiquette: Sense of Proportion in Group Chats

The default configuration contains a brilliant section regarding group chats:

  • ❀
    Don’t Spam: If there’s no substantive content, don’t send “Hmm” or “Nice.”
  • ❀
    Know When to Shut Up: If the conversation is flowing well, don’t force an interruption.
  • ❀
    Use Reactions: On Discord/Slack, use Emoji reactions instead of meaningless text replies.

This design makes the AI no longer a chattering radio station, but a participant who knows how to read the room.

9. Practical Summary & Action Checklist

To facilitate quick implementation, here is the core action checklist for configuring OpenClaw.

Action Checklist

  1. Locate Directory: Confirm workspace via ls ~/.openclaw/workspace/.
  2. Modify SOUL: Define personality and red lines in SOUL.md. Keywords: Specific, Snarky attributes, Set Red Lines.
  3. Configure AGENTS: Write “Wake-up Protocol” in AGENTS.md to force AI to read files before starting work. Keywords: SOP, Memory Management, Safety Boundaries.
  4. Refine USER: Fill in your timezone, blacklist words, and current focus in USER.md. Keywords: Personalization, De-AI-flavor.
  5. Set Heartbeat: Add active monitoring tasks (e.g., price alerts, Twitter monitoring) in HEARTBEAT.md. Keywords: Proactive, Scheduled.
  6. Check Permissions: Ensure tools permission in openclaw.json is full and configure API variables in TOOLS.md.

One-Page Summary

File Name Function Positioning Core Function Key Configuration Content
SOUL.md Soul Determines personality & values Personality setting, Absolute red lines, Long-term directives
AGENTS.md Work Guide Standardizes workflow & decision logic Wake-up protocol, Memory management, Boundary interception
USER.md User Profile Achieves personalized service Timezone, Formatting fetishes, Current focus, Minefields
HEARTBEAT.md Heartbeat Enables active service & monitoring Scheduled tasks, Conditional trigger alerts
TOOLS.md Tool Config Defines organs & organ parameters API aliases, File path mapping
IDENTITY.md Identity Defines external image Name, Species, Vibe, Avatar
BOOTSTRAP.md Guide Initialization config flow First run only, Deletes after configuration

10. Frequently Asked Questions (FAQ)

Q1: Do I need to restart the OpenClaw service after modifying these .md files?
A: Generally, configuration file changes take effect in the next session or heartbeat cycle without requiring a manual service restart. However, to ensure immediate effect, it is recommended to restart the OpenClaw process or reconnect the session.

Q2: My SOUL.md is very long, but the AI seems to ignore the content at the end. What should I do?
A: Large model context windows are limited. It is recommended to keep SOUL.md concise. Move specific workflow rules to AGENTS.md and tool parameters to TOOLS.md. SOUL.md should only retain the core identity and red lines.

Q3: I set tasks in HEARTBEAT.md, but the AI has no reaction. Why?
A: First, check if the heartbeat cycle is configured correctly; second, confirm if AGENTS.md grants the AI permission to read HEARTBEAT.md (in the wake-up protocol). If the file is empty or contains only comments, the AI will skip the call.

Q4: Why are “Blacklist Words” in USER.md important?
A: This is the most direct method to remove “AI flavor.” Large model training data contains a lot of polite filler like “happy to help.” Explicitly banning these words in USER.md forces the model to generate hardcore content that fits your taste.

Q5: What is the relationship between TOOLS.md and files in the Skills directory?
A: The Skills directory stores the code logic of third-party skills (manual), while TOOLS.md is your personalized configuration for these skills (cheat sheet). For example, skill code determines AI can “send email,” but TOOLS.md determines the SMTP server address or default sender nickname used.

Q6: What if I accidentally delete SOUL.md?
A: OpenClaw usually has a default backup mechanism. If deleted, the AI will revert to the default factory setting state, behaving like a generic chatbot. You will need to rewrite your personalized configuration.

Q7: How can I make AI safer in local file operations?
A: Explicitly state in the “Absolute Red Lines” of AGENTS.md: Forbid using the rm command, force using the trash command. This ensures files are moved to the recycle bin rather than permanently deleted even if the AI misjudges.

Q8: When will BOOTSTRAP.md be deleted?
A: According to design logic, the AI should actively delete this file after completing all initialization questions (confirming identity, user, contact channels). If you find the file persists, it means the initialization process might be incomplete or stuck; check the AI’s logs.