Best Practices
Battle-tested tips from daily OpenClaw use. The first 6 are about training your agent well; the last 4 are practical tricks from real workflows.
1. Memory Reinforcement: Preventing Agent Amnesia
Agents lose context over time — especially after long sessions get auto-compressed. Previous decisions and rules can vanish mid-task.
Three defenses:
memory/ directory. Keep dated work notes (e.g., memory/2026-03-08.md). The agent reads recent entries on startup to restore context. Note key decisions and daily progress — no need to be exhaustive.
SESSION.md. For complex tasks, maintain a SESSION.md in the project root with: current goal, key decisions made, approaches ruled out, and current progress. Update every 20–30 minutes. Even if compaction fires, the essentials survive.
Manual /compact. When context feels full, don't wait for auto-compression. Run /compact with a custom prompt specifying what must be preserved. The default compression keeps "what you're doing" but drops "why" and "what was rejected."
Two minutes writing a note beats twenty minutes re-explaining context.
2. Identity Definition: Write a SOUL.md for Each Agent
SOUL.md isn't just a name and emoji. It shapes how the agent understands its role and interacts with you.
Agents without a clear identity drift — they respond in English when you write Chinese, give verbose analysis instead of direct answers.
Give the agent a name, set a personality (sharp / warm / chaotic / calm), pick a signature emoji. These settings genuinely influence output style: "sharp" agents are more concise and direct; "warm" agents are more patient. Be specific — the clearer the role, the less the agent goes off-track.
3. User Profile: Write a USER.md
USER.md tells the agent who you are, your preferences, and your timezone. The agent uses this to adjust its behavior automatically.
For example: "Writing style preference: pragmatic, conversational but not dramatic, like chatting with a peer." The agent will reference this every time it writes — no need to repeat it each session.
Don't forget your timezone. Scheduled tasks, reminders, and log timestamps all depend on it. Without it, the agent defaults to UTC, and your times will be off.
4. Autonomous Permissions: Fewer Confirmations, More Flow
By default, agents ask "are you sure?" before many actions. File reads, web searches, command execution — confirming every one cuts efficiency in half.
Configure an allowlist in openclaw.json for common low-risk operations. Reading files, searching, writing markdown — fully automatable. Keep confirmations only for deletions, config changes, and external publishing.
Low risk: automate. High risk: require approval. Same logic as employee delegation — you don't approve every email, but contracts need your sign-off.
5. Skill Loading: Keep Upgrading Agent Capabilities
Skills are the fastest way to add new abilities. Each skill is a Markdown file defining a workflow — the agent follows the steps.
ClawHub has 10,000+ community skills covering most common needs. Install by dropping a SKILL.md into the agent's skills directory — it's available after next startup. Updating is the same: replace the file.
Writing your own skill isn't hard. Describe what you want the agent to do, what steps to follow, and what format to output. The more specific, the more reliable.
Don't install too many at once. Master two or three first, then expand. Too many skills cause the agent to get confused about which to apply.
6. Daily Training: Teach While Working
An agent isn't done once configured — it needs ongoing training, like a new employee.
Three habits:
Log mistakes in LEARNING.md. After every error: what went wrong + why + what to do differently. The agent reads this file on startup, so the same mistake won't recur.
Daily memory/ entries build understanding. Work notes aren't just for preventing amnesia — they also help the agent learn your working style. Over time it gets better at anticipating your preferences.
Correct specifically. When output is wrong, don't just say "that's wrong." Say where and how to fix it. Repeated style corrections will shift the agent from "analyst report tone" to whatever voice you actually want.
Early investment in training pays off — you'll spend less time correcting later.
7. Image Automation: Let the Agent Manage Its Own Images
During conversations, screenshots and web assets accumulate that you want in documents.
Solution: give the agent an image host upload capability. When it receives a screenshot, it uploads to CDN, gets a public URL, and inserts directly into Notion via API — zero manual steps.
The setup: Cloudflare R2 as the image host (S3-compatible, free tier is plenty), plus a 30-line Node.js upload script in the agent's workspace. Core logic: read file → hash with MD5 → generate path by year/month/md5.ext → upload to R2 → return CDN URL.
Any S3-compatible host works: Alibaba Cloud OSS, Tencent COS, MinIO. Set it up once; all image-related work is handled automatically.
8. Multi-Agent Sharing: Reuse Config and Scripts
Multiple agents within one instance each have their own workspace by default — nothing is shared. A capability you give one agent (R2 upload, Notion API) isn't automatically available to others.
Solution: a shared directory with symlinks. Create a shared/ folder in the instance directory for common scripts and config. Link it into each agent's workspace. Add a note in each agent's SOUL.md to check shared/SHARED.md when they need shared resources.
One change propagates to all agents. Adding a new agent just requires creating one symlink.
9. Safe Config Editing: Don't Let the Agent Break Itself
Hard-won lesson: if you only have one instance and ask it to modify its own openclaw.json, a typo can trigger restart loops — and then you can't talk to it anymore.
Real example: asked an agent to add an AI provider. It wrote providers at the root level instead of under models.providers. Config validation failed, the instance restarted 36 times.
Precautions:
- Before modifying config, have the agent read the docs to confirm the field hierarchy
- With a single instance, a bad config means manual terminal intervention
- Use a second instance to manage configs — it can fix the first one if something goes wrong
Also: if the agent's responses include a wall of English "reasoning" text that looks like noise, run /thinking off to suppress it.
10. Team Collaboration: Add the Agent to a Telegram Group
Having team members chat directly with an AI in a Telegram group is the simplest form of team collaboration.
Three steps:
Step 1: Invite the bot to the group. Go to BotFather, disable Privacy Mode (/setprivacy → Disable). After disabling, remove and re-add the bot for the setting to take effect. Or just make the bot a group admin — admins bypass privacy mode.
Step 2: Get the group ID. Send a message in the group, then visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser. Find chat.id in the JSON — a negative number is the group ID.
Step 3: Update openclaw.json:
{
"channels": {
"telegram": {
"groupPolicy": "open",
"groups": {
"-5202339810": {
"requireMention": false
}
}
}
}
}
Important pitfall: setting groupPolicy to open alone isn't enough. You must also set requireMention: false. Without it, the bot only responds to @mentions, and you'll see reason: no-mention in logs — everything looks fine but the bot ignores messages.
Restart the gateway for config changes to take effect. For an immediate temporary fix, send /activation always in the group — works instantly but resets after restart.
All 10 tips come down to one principle: treat your agent like a new employee.
Invest time upfront in SOUL.md, USER.md, and LEARNING.md, and get the memory system running. You'll find the agent becomes more useful — and less work — over time.