The OpenClaw Tuning Manual: 7 Advanced Configurations That Take It from "Usable" to "Indispensable"

The OpenClaw Tuning Manual: 7 Advanced Configurations That Take It from "Usable" to "Indispensable"

AI教程
17NAS17NAS
2026/2/28
1469 reads

Before we start: this article assumes you already have the basics

If you have already:

  • Installed OpenClaw and can chat normally with it (Discord / Telegram / WebChat all work)
  • Written an SOUL.md / USER.md / IDENTITY.md
  • And you know about MEMORY.md,memory/ the layered file structure, and roughly what memorySearch is

Then you can read straight on.

I will cover seven topics, all of them practical configuration points you can apply immediately:

  1. AGENTS.md: give the AI a working manual (the most important one)
  2. Memory in practice: make the AI genuinely remember, and maintain itself
  3. Sub-agents: turn one person into a small team (parallelism + context isolation)
  4. Cron jobs: automation accurate to the minute
  5. Skill development: teach the AI new tricks (writing a skill from scratch)
  6. Multi-channel access: reach your AI anywhere
  7. A configuration cheat sheet: recommended values and the usual traps

At a glance: from "previous article" to "after this tuning"

Dimension Previous article After this article Behaviour rules SOUL.md a few principles A working manual: what to read, what to write, what to ask Memory Layered structure + searchable Auto-written, auto-compressed, weekly maintenance, better hits Task capability Single-threaded main brain Can dispatch sub-agents to work in parallel and summarise results Automation Heartbeat checks Precise Cron scheduling; daily and weekly reports send themselves Extensibility Install ready-made skills Write your own skills — add whatever capability you need Channels One platform only Discord/Telegram/WebChat online at the same time Configuration Good enough to run Common parameters tuned for stability and token efficiency

1. AGENTS.md: writing a "working manual" for your AI

1) What problem does it solve?

SOUL.md defines "who it is",USER.md defines "who it is helping", but many people overlook this:the AI has no idea how it should work.

For example:

  • When a new session starts, which file should it read first? In what order?
  • Where should memories be written? In what format?
  • Which actions can it take directly, and which must it ask you about first?
  • Can it quote your private memories in a group chat?

That is the value of AGENTS.md: it is not a personality setting, it is aworking manual.

Think of it this way:

  • SOUL.md = personality ("speak plainly, lead with the conclusion")
  • AGENTS.md = SOP ("what to read first, what to do next, how to record it, what is off-limits")

2) The session startup flow: what should the AI do first when it wakes up?

A new session is essentially "just woken up" — it does not automatically carry the context of your last conversation. You need to hard-code the "restore the scene" procedure.

Add a section to AGENTS.md (writing the rules in English tends to be more reliable):

Every Session

Before doing anything else:

  1. Read SOUL.md — this is who you are
  2. Read USER.md — this is who you're helping
  3. Read memory/YYYY-MM-DD.md (today + yesterday) for recent context
  4. If in MAIN SESSION (direct chat with your human): Also read MEMORY.md

Don't ask permission. Just do it.

Why read both today’s and yesterday’s logs? Because in the early hours "today" may still be empty — only yesterday has content.

Why read MEMORY.md only in the MAIN SESSION? Because MEMORY.md usually holds more private, more sensitive index information, which should not be loaded in group chats or in cron/sub-agent sessions.

3) Memory writing rules: teach it to record "reusable conclusions"

When someone’s memory system falls apart, it is usually not a problem with the layered structure but withundefined writing rules.

There are usually two outcomes:

  • Everything gets dumped into MEMORY.md (which turns into a running log)
  • Or nothing gets written at all (so it forgets by next time)

It helps to pin down "where to write, what to write, and how to write it". For example:

Memory

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

Memory layers

Layer File Purpose Index MEMORY.md Core information and index, kept lean (under 40 lines is ideal) Project memory/projects.md Current status and to-dos for each project Infrastructure memory/infra.md Quick reference for servers, APIs, and deployment config Lessons memory/lessons.md Mistakes made, graded by severity Daily log memory/YYYY-MM-DD.md Raw daily records (but record conclusions)

Writing rules

  • Daily log: write what happened that day into memory/YYYY-MM-DD.md, in a fixed format
  • Project status: update memory/projects.md
  • Lessons: after a mistake, write it into memory/lessons.md
  • MEMORY.md: update only when the index changes, and keep it lean

Iron rules

  • Record conclusions, not the process
  • Use tags so memorySearch can find them
  • If you want to remember it, write it to a file — do not rely on "keeping it in your head"

A workable log format looks like this:

[PROJECT:name] Title

  • Conclusion: one-sentence summary
  • Files changed: the files involved
  • Lessons: the pitfalls hit (if any)
  • Tags: #tag1 #tag2

The advantage of this format is that when you search keywords with memorySearch, the hits are more focused and cleaner.

4) Safety boundaries: what it may do, and what it must ask about

It is worth drawing the "internal vs external" line clearly, or you will hit trouble sooner or later (especially with group chats and automated tasks).

Safety

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

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

Group Chats

You have access to your human's stuff. That doesn't mean you share it.
In groups, you're a participant — not their voice, not their proxy.

2. Memory in practice: making the AI truly "remember" and maintain itself

You have probably run into these three typical problems:

  1. After a long conversation it suddenly "loses its memory" (details are dropped when the dialogue is compressed)
  2. The logs grow and grow, quality varies wildly, and search hits become more and more of a lottery
  3. Nobody maintains the memory, so stale information piles up into noise

This chapter tackles those three problems one by one.

1) memoryFlush: write important information to disk before compression

OpenClaw triggers compaction when the context approaches its limit. Compaction itself is normal, butcompaction can lose details.

The fix: enable memoryFlush so it writes to disk before compacting.

Add this to openclaw.json (example):

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

A quick word on how to read the recommended values:

  • reserveTokensFloor=20000: after compaction, always keep at least one stretch of "recent conversation"
  • softThresholdTokens=4000: flush triggers when fewer than 4000 tokens remain (too small and it cannot write anything; too large and it fires far too often)

2) Making memorySearch more accurate: one log entry, one topic

Vector retrieval is not afraid of you writing little — it is far more afraid of you writing a jumble.

In practice, the format with the best hit rate is:

  • State the topic in the title (nginx reverse proxy, IPv6, port conflicts, and so on)
  • Put the conclusion in a fixed position
  • Fill in synonyms as tags (#deploy #nginx #reverse-proxy)

Unstructured running commentary dilutes the similarity score, which is why searching it feels like reading tea leaves.

3) Weekly automatic maintenance: preventing "memory rot"

Once the logs pile up, stale information pollutes your search results. My approach: turn maintenance into a fixed procedure and have the AI run it once a week.

You can add a "weekly maintenance" job to HEARTBEAT.md, paired with a state file to control the frequency:

  • memory/heartbeat-state.json records the date of the last maintenance run
  • The heartbeat checks whether "7 or more days have passed since the last maintenance"
  • If so, it runs: distill, compress, clean up, update the date

I recommend three categories of maintenance work:

  • Distil: move the long-term useful material into projects.md / lessons.md
  • Compress: collapse one-off tasks from a long log entry into a single line of conclusion
  • Clean up: information that is completely expired (for example, "meeting tomorrow")

3. Sub-agents: turning one person into a small team (parallelism + isolated context)

1) What exactly do sub-agents solve?

The problem with a single-threaded main brain is that when a complex task arrives, it either drags on for ages or you cannot get a word in mid-way.

Sub-agents bring two main benefits:

  • Parallelism: you can dispatch two helpers to each handle a piece at the same time
  • Context isolation: a sub-agent’s long task will not blow up the main conversation

2) The easiest trap to fall into: sub-agents start with "zero context"

A sub-agent only sees the task description the main brain gives it, so a sloppy task produces a sloppy result.

A good task description should include at least:

  • The goal (what should be produced)
  • File paths (which files to read and write)
  • Constraints (read-only? what must not be changed? what are the conventions?)
  • Acceptance criteria (what counts as done)

Treat the task as a briefing written for a "smart but unfamiliar colleague" — the more specific, the more reliable.

3) Concurrency advice: start with two sub-agents

Dispatching too many agents at once very easily triggers API rate limiting (429). In practice:

  • Ordinary personal quota: two at a time is the most stable
  • Large quota / local models: you can try three
  • Four or more will most likely start hitting 429 (especially with web search or tool calls involved)

4. Cron jobs: automation accurate to the minute

1) Heartbeat vs Cron: do not mix them up

  • Heartbeat: suits lightweight "check on it in passing" tasks (low precision)
  • Cron: suits tasks that "must run at exactly this time" (accurate to the minute)

If you want "send a morning report at 9:00 every day" or "send a weekly report at 10:00 every Monday", Cron is the better fit.

2) The most commonly used cron expressions

  • 0 9 * * *: every day at 9:00
  • 0 9 * * 1: every Monday at 9:00
  • 0 9,18 * * *: every day at 9:00 and 18:00
  • */30 * * * *: every 30 minutes

Always set the time zone tz, otherwise it defaults to UTC and your times will be off by eight hours (the most common trap in UTC+8).

5. Skill development: writing a usable skill from scratch

1) What is a skill?

It is essentially an operating manual in Markdown.

OpenClaw puts each skill’s description into the system prompt. When the user sends a message, it matches which skills might be triggered — and once there is a match, it reads the corresponding SKILL.md and follows the steps.

So description is not about "writing elegantly" but about "covering everything".

  • frontmatter (name/description)
  • What to do first once triggered
  • The steps (ideally executable and reproducible)
  • Output format (a fixed template)
  • Error handling (always include it)

3) A practice suggestion: start with an IP lookup skill

A skill like "IP geolocation lookup" is ideal for beginners: simple trigger, clear steps, fixed output, and easy error handling.

One principle when writing skills: run the process by hand first, then write the process down as a skill. That gives the highest success rate.

6. Multi-channel access: keep the AI online without letting it say the wrong thing

The point of multi-channel access is not "connecting many channels" but two things:

  1. Source control:allowFrom keep it tight (server/user/channel)
  2. Format adaptation: different platforms support Markdown to different degrees (tables especially)

If you use Discord and Telegram side by side, write the "platform formatting rules" into AGENTS.md:

  • Discord: tables and code blocks are both fine
  • Telegram: tables are unstable, so prefer lists
  • WhatsApp: treat it essentially as plain text

7. Configuration cheat sheet: how to tune the common parameters for stability

In this chapter I keep only the points I think deliver a clear payoff, so you are not buried in configuration from the start.

1) blockStreaming: do not make long replies wait until the very end

Let the AI send long replies in chunks, which feels much more like "typing in real time".

Recommendation:

  • blockStreamingDefault: "on"
  • minChars: 200 (too small and it floods the channel)
  • maxChars: 1500 (too large and streaming loses its point)

2) ackReaction: give you an "I got it" signal first

This matters especially on instant-messaging platforms like Discord and Telegram. Otherwise you will assume it has hung.

3) compaction + memoryFlush: lose as little key information as possible, however long you chat

You only need to remember one line: write to a file before compacting. That is what memoryFlush is for.

4) Heartbeat activeHours: do not disturb you in the middle of the night

If you have enabled heartbeat checks, set activeHours, for example 08:00–23:00. That way it will not message you while you are asleep.

If you do not want to do everything at once, follow this priority order — it is the most reliable:

  1. AGENTS.md: startup flow + memory rules + safety boundaries
  2. Enable memoryFlush (so even a long conversation rarely loses key points)
  3. Configure ackReaction (the experience improves immediately)
  4. Turn on blockStreaming (long output becomes much more comfortable)
  5. Add activeHours to Heartbeat (no interruptions)
  6. Then consider Cron, sub-agents, skills, and multi-channel (add as needed)

Article navigation (optional)

Back to article list