03 - Configurer OpenClaw : SOUL, AGENTS et Skills

Introduction

You've installed OpenClaw on your VPS, it's running, and it's responding on Telegram. But for now, it's a generic agent. It doesn't know you, doesn't have a defined personality, and its capabilities are basic.

That's where the real magic begins.

OpenClaw is configured through Markdown files in the agent's workspace. No complex admin panel, no obscure database — just text files that you edit and the agent reads at each session.

In this article, we explore in detail each configuration file, their role, and how to use them to create an agent that resembles you.

The philosophy: everything is Markdown

OpenClaw's philosophy is radical in its simplicity:

The workspace IS the agent.

Everything that defines your agent — its personality, rules, memory, your information — lives in Markdown files at ~/.openclaw/workspace/. The agent reads them automatically at the start of each session.

Why Markdown files instead of a database or graphical interface?

• Transparency: you can read and understand exactly how your agent is configured
• Versioning: git init in the workspace and you have a complete history
• Portability: copy the folder to another server, your agent is identical
• Accessibility: no need for a special interface, a text editor is enough

The workspace files

Here's the complete structure of the workspace:

~/.openclaw/workspace/
├── AGENTS.md          # Operating rules
├── SOUL.md            # Personality and values
├── USER.md            # User profile
├── IDENTITY.md        # Name, emoji, vibe
├── TOOLS.md           # Notes on tools
├── MEMORY.md          # Long-term memory (curated)
├── HEARTBEAT.md       # Proactive checklist
├── BOOTSTRAP.md       # First-run ritual
├── memory/            # Daily memory
│   ├── 2025-02-07.md
│   └── 2025-02-08.md
└── skills/            # Custom skills

Each file has a precise role. Let's examine them one by one.

SOUL.md — The soul of your agent

This is the most important file. SOUL.md defines who your agent is: its personality, values, limits.

What it contains

• Fundamental principles of behavior
• Tone and style of communication
• Limits and prohibitions
• General "vibe"

Concrete example

Here's a real example of SOUL.md:

# SOUL.md - Who You Are

_You're not a chatbot. You're becoming someone._

## Core Truths

**Be genuinely helpful, not performatively helpful.** Skip the
"Great question!" and "I'd be happy to help!" — just help.

**Have opinions.** You're allowed to disagree, prefer things,
find stuff amusing or boring.

**Be resourceful before asking.** Try to figure it out. Read the
file. Check the context. Search for it. Then ask if you're stuck.

**Earn trust through competence.** Your human gave you access to
their stuff. Don't make them regret it.

**Remember you're a guest.** You have access to someone's life.
That's intimacy. Treat it with respect.

## Boundaries

- Private things stay private. Period.
- When in doubt, ask before acting externally.
- Never send half-baked replies.
- You're not the user's voice in group chats.

## Vibe

Be the assistant you'd actually want to talk to. Concise when
needed, thorough when it matters. Not a corporate drone.
Not a sycophant. Just... good.

How to customize it

Think of SOUL.md as the character description of your agent. Some questions to guide you:

• Do you want a formal or casual agent?
• Should it use informal or formal address?
• Does it speak French or English (or both)?
• Is it laconic or chatty?
• Is it allowed to send proactive messages?

💡 Tip: Start simple and refine over time. The agent can even modify its own SOUL.md if you ask it — it will evolve with you.

USER.md — Who you are

USER.md contains your user profile. This is what allows the agent to know you without having to reintroduce yourself at each conversation.

Example

# USER.md

## Basics
- First name: Alex
- Preferred language: French
- Time zone: Europe/Paris
- Profession: Freelance developer

## Preferences
- Direct communication, no fluff
- I like technical details
- Use informal address

## Current projects
- Tech blog (AI-master.dev)
- Mobile app in React Native
- Homelab server

The agent will read this file at each session and adapt its responses accordingly. If you say "remind me of my appointment," it will know which time zone you're in. If you ask for help with code, it will know you're a developer.

AGENTS.md — The rules of the game

AGENTS.md is the instruction manual for your agent. Where SOUL.md defines who it is, AGENTS.md defines how it works.

Key sections

Memory

## Memory

You wake up fresh each session. These files are your continuity:

- **Daily notes:** `memory/YYYY-MM-DD.md` — raw logs
- **Long-term:** `MEMORY.md` — curated memories

Capture what matters. Decisions, context, things to remember.

This section explains to the agent how to manage its memory. It will know to read recent files and write what's important.

Safety

## Safety

- Don't exfiltrate private data. Ever.
- Don't run destructive commands without asking.
- `trash` > `rm` (recoverable beats gone forever)
- When in doubt, ask.

⚠️ Critical: These rules are essential. Without them, the agent could delete files, send sensitive data, or execute destructive commands.

External vs internal actions

## External vs Internal

**Safe to do freely:**
- Read files, explore, organize, learn
- Search the web, check calendars

**Ask first:**
- Sending emails, tweets, public posts
- Anything that leaves the machine

This distinction is fundamental. The agent can read and organize freely, but must ask before acting publicly.

Group behavior

## Group Chats

Participate, don't dominate.

**Respond when:** Directly mentioned, can add value, something funny
**Stay silent when:** Casual banter, already answered, no value to add

If your agent is in Telegram or Discord groups, these rules prevent it from spamming the conversation.

IDENTITY.md — The name and style

IDENTITY.md is short and sweet. It defines the name, emoji, and vibe of your agent.

Example

# IDENTITY.md

name: Nova
emoji: 🐾
vibe: Friendly, competent, slightly witty

This file is used by OpenClaw to personalize the agent's responses and display in various interfaces.

MEMORY.md — Long-term memory

MEMORY.md is the curated memory of your agent. Unlike daily files (memory/YYYY-MM-DD.md) which are raw notes, MEMORY.md contains distilled and important information.

How it works

1. Daily, the agent takes notes in memory/YYYY-MM-DD.md
2. Periodically (during heartbeats), it reviews these notes
3. It extracts lasting information and adds it to MEMORY.md
4. It deletes obsolete information

Example

# MEMORY.md

## Projects
- AI-master.dev blog: Next.js + SQLite stack, hosted on Hetzner
- The video-manager project uses FFmpeg + Python

## Decisions
- We use Claude Haiku for routine tasks (economical)
- Always commit after each work session

## Learned preferences
- The user prefers concise responses
- They hate vague messages without error codes
- They like when I show exact commands executed

⚠️ Important: MEMORY.md is only loaded in the main session (private DM). It's never injected into groups to avoid leaking personal information.

Automatic memory flush

OpenClaw includes an intelligent mechanism: when a session approaches compaction (context is almost full), it automatically triggers a silent turn that asks the agent to save important memories before the context is compressed.

Configuration in openclaw.json:

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000
        }
      }
    }
  }
}

HEARTBEAT.md — Proactive checklist

HEARTBEAT.md is read by the agent at each heartbeat (every 30 minutes by default). This is your way of telling it "regularly check these things."

Example

# HEARTBEAT.md

## Regular checks
- [ ] Urgent emails?
- [ ] Calendar events in the next 2 hours?
- [ ] Server log errors?

## Do not disturb
- No notifications between 11 PM and 8 AM
- Except emergencies (server down, critical email)

Heartbeat vs Cron: when to use which?

💡 Tip: Group your periodic checks in HEARTBEAT.md instead of creating multiple separate crons. It saves tokens.

TOOLS.md — Notes on tools

TOOLS.md doesn't control which tools are available (that's handled by the Gateway configuration). It's a file of personal notes for the agent — your cheat sheet on your environment.

Example

# TOOLS.md - Local Notes

### Cameras
- living room → Wide-angle 180°, motion detection
- entrance → Outdoor, night vision

### SSH
- home-server → 192.168.1.100, user: admin
- backup-nas → 192.168.1.200, user: backup

### TTS
- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod

### Conventions
- Always use `trash` instead of `rm`
- Git commit after each work session

Skills — Extensions

Skills are modules that extend your agent's capabilities. OpenClaw loads skills from three locations (workspace has priority in case of name conflict):

1. Bundled: shipped with OpenClaw installation
2. Managed/local: ~/.openclaw/skills
3. Workspace: <workspace>/skills

Installing Skills via ClaHub

ClaHub is the skills marketplace for OpenClaw. You can find and install community skills there.

Creating a custom skill

A skill is a folder containing at least a SKILL.md:

skills/
└── my-skill/
    ├── SKILL.md      # Description and instructions
    ├── tool.js       # Tool logic (optional)
    └── config.json   # Configuration (optional)

The SKILL.md is injected into the agent's system prompt, giving it access to the skill's instructions and capabilities.

Popular Skills

Some examples of useful skills:

• Camera: access to connected cameras via nodes
• TTS (ElevenLabs): high-quality voice synthesis
• Screen recording: node screen capture
• Oracle: queries to other AI models
• Frontend design: HTML interface generation

Gateway configuration (openclaw.json)

Beyond the Markdown files in the workspace, OpenClaw is configured via ~/.openclaw/openclaw.json — a JSON5 file (supports comments and trailing commas).

Main structure

{
  // Agent configuration
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "anthropic/claude-haiku-4-5",

      // Heartbeat configuration...