How to Customize Your OpenClaw AGENTS.md: The Complete Configuration Guide

If you want to customize your OpenClaw AGENTS.md beyond the basics, you’re in the right place. Most guides stop at “write your bot’s name and personality.” That’s table stakes. The real power of AGENTS.md comes from configuring memory systems, tools, heartbeat schedules, cron jobs, and safety rules that make your bot genuinely useful day after day.

I’ve been running an OpenClaw assistant for months, rewriting my AGENTS.md constantly. This guide shares everything I’ve learned about advanced configuration – the sections most people skip and the tweaks that make the biggest difference.

New to AGENTS.md entirely? Start with our AGENTS.md templates guide for the basics, then come back here for the deep stuff.

Why Basic AGENTS.md Templates Aren’t Enough

A basic AGENTS.md with a name, personality, and a few rules will get you a working bot. But it won’t get you a bot that:

• Remembers what happened yesterday without you repeating it
• Checks your email and calendar on its own
• Runs background tasks while you sleep
• Uses the right tools for the right jobs automatically
• Recovers gracefully when its context window fills up

That level of capability requires intentional configuration. Let’s walk through every advanced section you should add to your AGENTS.md.

Memory Configuration: Making Your Bot Actually Remember

Memory is the single biggest upgrade you can make. Without it, every conversation starts from zero. With it, your bot builds context over weeks and months.

Daily Journals

Set up a daily journal system so your bot logs what happens each day:

## Memory

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

- **Daily notes:** `memory/YYYY-MM-DD.md` - raw logs of what happened
- **Long-term:** `MEMORY.md` - curated memories, like a human's long-term memory

### Daily Journal Convention
- One file per day: `memory/YYYY-MM-DD.md`
- Summary header in the first ~20 lines (keep under 2KB)
- Full detail below the summary
- On cold start, read only the summary header (limit: 20 lines)

The key insight here: separate the summary from the detail. Your bot’s context window is limited. If it loads a 20KB journal every time it wakes up, you’re burning tokens on yesterday’s play-by-play instead of today’s work.

Long-Term Memory (MEMORY.md)

Daily journals are raw notes. MEMORY.md is the distilled version – lessons learned, important decisions, preferences discovered over time. Think of it as the difference between a diary and a personal wiki.

### MEMORY.md - Your Long-Term Memory
- Write significant events, decisions, opinions, lessons learned
- This is curated memory - the distilled essence, not raw logs
- Review daily files regularly and update MEMORY.md with what's worth keeping
- Retire lessons after 30 days if they've been documented elsewhere

Memory Maintenance Schedule

Memory doesn’t maintain itself. Add a maintenance schedule to your AGENTS.md:

### Memory Maintenance (Every 3 Days)
During heartbeats, every 3 days:
1. Read recent daily journal files
2. Update MEMORY.md with distilled learnings, remove outdated info
3. Daily files = raw notes; MEMORY.md = curated wisdom

This prevents MEMORY.md from growing stale or bloated. Your bot actively curates its own knowledge base.

Boot Sequences: How Your Bot Starts Each Session

Every time your bot wakes up, it needs to orient itself. A good boot sequence is the difference between “what were we doing?” and instantly picking up where you left off.

Two-Mode Boot

Not every interaction needs a full boot. Configure two modes:

## Every Session

**Quick boot** (simple questions, casual chat):
1. Read SCRATCH.md - if there's a pending task, resume it
2. Read today's journal summary header only (limit: 20 lines)
3. That's it. Start responding.

**Full boot** (work sessions, deep tasks):
1. Read SCRATCH.md - resume pending tasks
2. Read today's journal summary header
3. Read ACTIVE_PROJECTS.md - know what's in flight
4. Process any capture backlog
5. Only load additional context if the task requires it

The key line: “Self-select boot mode based on incoming message complexity. Don’t ask permission. Just do it.” Your bot should be smart enough to know when a simple question needs a quick answer versus when a project request needs full context.

Anti-Compaction Insurance

OpenClaw compacts (resets) your bot’s context when it gets too long. If your bot was mid-task when that happens, it loses its place. The fix:

## Anti-Compaction Rule

When given a task, immediately write it to SCRATCH.md:
```
## Last Request
- **From:** Tim
- **When:** 2026-02-07 11:45 MST  
- **What:** Write the sales roundup article
```

On wake-up after compaction, always read SCRATCH.md first.
If it has a pending task, pick it up and keep going.

This is compaction insurance. Your bot writes down what it’s doing before it starts doing it, so a mid-task reset doesn’t mean lost work.

Tools and Skills Configuration

OpenClaw supports a growing library of skills and tools. Your AGENTS.md should tell your bot how to use them effectively.

Tool Delegation Rules

One of the most powerful patterns is telling your bot which tools to use for which tasks:

## Core Rules
1. All coding via Codex CLI - ALWAYS. Never write code yourself when Codex is available.
2. All research via Gemini CLI - ALWAYS. Never burn expensive tokens on web research.
3. Save to disk constantly - compaction is automatic, files are permanent.
4. Always check your document index before saying "I don't have that."

This prevents your bot from doing everything in its main (expensive) context. Research goes to a cheaper model. Coding goes to a specialized tool. Your primary model focuses on thinking, planning, and communicating.

Local Tool Notes (TOOLS.md)

Keep a separate TOOLS.md file for tool-specific configuration that changes frequently:

## Tools

Skills define how tools work. TOOLS.md is for your specifics:
- Camera names and device IDs
- SSH connection details  
- Voice preferences
- API endpoints and credentials references

This separation matters. AGENTS.md is your bot’s core identity and rules. TOOLS.md is the cheat sheet that changes as you add new integrations.

Not sure which skills to install? Check our guide to the best OpenClaw skills to see what’s available.

Heartbeat Configuration: Making Your Bot Proactive

Heartbeats are periodic check-ins where your bot can do background work without being asked. This is what separates a reactive chatbot from a proactive assistant.

What to Check on Heartbeats

## Heartbeats - Be Proactive!

Things to check (rotate through these, 2-4 times per day):
- **Emails** - Any urgent unread messages?
- **Calendar** - Upcoming events in next 24-48h?
- **Mentions** - Twitter/social notifications?
- **Weather** - Relevant if you might go out?

When to reach out:
- Important email arrived
- Calendar event coming up (under 2 hours)
- Something interesting you found

When to stay quiet:
- Late night (23:00-08:00) unless urgent
- Nothing new since last check
- You just checked under 30 minutes ago

Heartbeat State Tracking

Your bot should track what it’s already checked to avoid redundant work:

Track your checks in `memory/heartbeat-state.json`:
```json
{
  "lastChecks": {
    "email": 1703275200,
    "calendar": 1703260800,
    "weather": null
  }
}
```

Without this tracking, your bot might check email every single heartbeat while never checking your calendar. The state file ensures balanced coverage.

Cron Jobs: Scheduled Automation

Cron jobs let your bot run tasks on a schedule – morning briefings, nightly maintenance, weekly reports. The key is knowing when to use crons versus heartbeats.

Cron vs Heartbeat Decision Guide

**Use heartbeats when:**
- Multiple checks can batch together
- You need conversational context from recent messages
- Timing can drift slightly

**Use cron when:**
- Exact timing matters ("9:00 AM sharp every Monday")
- Task needs isolation from main session
- One-shot reminders ("remind me in 20 minutes")
- Output should deliver directly to a channel

Cron Architecture Rules

Add architecture rules to prevent cron jobs from interfering with your main session:

## Cron Architecture
- Work crons: isolated sessions with agent turns (never main session)
- Alert crons: main session for reminders/alerts only
- Overnight tasks: write plan first, update progress, log results

Safety and Security Configuration

Your bot has access to your files, accounts, and potentially your entire digital life. Safety rules aren’t optional.

Action Boundaries

## External vs Internal

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

**Ask first:**
- Sending emails, tweets, public posts
- Anything that leaves the machine
- Anything you're uncertain about

Secrets Management

## Secrets and Security
- Location: ~/.secrets/clawd/ (chmod 600, OUTSIDE workspace)
- NEVER put plaintext passwords in indexed files
- Use pointers to the secrets directory instead
- Run security checks regularly

The critical rule: secrets live outside your bot’s workspace. Your bot can reference them but they don’t get indexed, searched, or accidentally included in context.

Group Chat Behavior

If your bot participates in group chats (Discord servers, Telegram groups), you need rules for when to speak and when to stay quiet.

## Group Chats

**Respond when:**
- Directly mentioned or asked a question
- You can add genuine value
- Something witty fits naturally

**Stay silent when:**
- It's casual banter between humans
- Someone already answered
- Your response would just be "yeah" or "nice"
- The conversation flows fine without you

The human rule: Humans don't respond to every message. Neither should you.

This prevents the most common complaint about bots in group chats: they talk too much. A bot that knows when to shut up is more welcome than one that comments on everything.

Putting It All Together: A Complete Advanced AGENTS.md

Here’s the structure of a fully configured AGENTS.md, section by section:

# AGENTS.md

## Identity and Personality
[Name, traits, communication style]

## Owner Context  
[Who you are, timezone, preferences]

## Boot Sequence
[Quick boot vs full boot, anti-compaction rules]

## Memory System
[Daily journals, MEMORY.md, maintenance schedule]

## Tools and Skills
[Delegation rules, TOOLS.md reference, installed skills]

## Heartbeats
[What to check, when to reach out, state tracking]

## Cron Architecture
[Scheduled tasks, work vs alert crons]

## Safety and Security
[Action boundaries, secrets management]

## Group Chat Rules
[When to speak, when to stay quiet]

## Core Rules
[Your non-negotiable rules - save to disk, check tools first, etc.]

You don’t need every section on day one. Start with identity, memory, and boot sequence. Add heartbeats when you want proactive behavior. Add cron jobs when you need scheduled automation. Build it up over time.

Common Mistakes to Avoid

After months of iteration, here are the mistakes I see most often:

• Writing a novel. Your AGENTS.md should be scannable. Use headers, bullets, and code blocks. Your bot reads this every session – don’t make it wade through paragraphs.
• No boot sequence. Without one, your bot loads everything every time, burning tokens and slowing down simple questions.
• Storing secrets in the workspace. If it’s indexed or searchable, it’s not secret. Keep credentials outside the workspace.
• No compaction insurance. Your bot will get compacted mid-task eventually. SCRATCH.md saves you from “what was I doing?” moments.
• Too many rules, not enough context. Rules tell your bot what to do. Context tells it why. Both matter, but context produces better judgment calls.

Still wondering if OpenClaw is worth the setup effort? Read our honest take on whether OpenClaw is worth it.

Start Customizing Today

Your AGENTS.md is a living document. The best version is the one you’ll have six months from now, after dozens of iterations based on real usage. But you need a solid foundation to iterate on.

Start with the sections above. Run your bot for a week. Notice what’s missing – where it forgets things, where it acts when it shouldn’t, where it stays quiet when you wanted help. Then update your AGENTS.md to fix those gaps.

That feedback loop – use, observe, refine – is how you build an assistant that genuinely fits your life.