Idle Builder Mode: after 60 minutes of user silence, the agent auto-selects a task from TODO.md and starts working. No prompting required.
Antelope Filter: before picking any task, the agent asks three questions — does this compound? is it revenue-linked? does it take a week+ to build? No to any = skip it, pick something that matters.
HEARTBEAT_OK protocol: healthy heartbeats are fully silent. The agent replies with exactly HEARTBEAT_OK and nothing is sent to the user. You only hear from the heartbeat when something is broken or shipped.
Anti-decay rule: if 3 consecutive autonomous waves are housekeeping-only (no real project shipped), the agent is forced to pick a real project next. Prevents busy-work spirals.
Priority ordering explicit: Revenue-generating → Visible shipping → Research → Fun/experimental. Enforced at task selection, not just mentioned in docs.
: when there is nothing to say, the agent sends (exact string only, full message). No filler, no "let me know if you need anything."
Pro Plan reality check: Opus is the ideal model for autonomous work. On a Pro plan, Sonnet is an acceptable substitute — update your config accordingly and don't fight it.
What's New in v4.1 (Recovery Edition)
4-file brain by default: AGENTS, MEMORY, TODO, TOOLS. Less markdown sprawl, better operator clarity.
Heartbeat got quieter and sharper: health checks only, actionable alerts only, HEARTBEAT_OK when clean.
Push discipline is explicit: repo allowlists for autonomous pushes, per-push permission outside the allowlist.
Living-example philosophy: this repo should reflect real operations, not theory slides.
Two-bot pattern: works in production when boundaries are clean and ownership is explicit.
How This Guide Is Organized
| Layer | What | Who it's for |
|-------|------|-------------|
| 🟢 Layer 1: Basic Uptime | Install, keep alive, don't crash | Everyone |
| 🟡 Layer 2: Core Rules | Security, config hygiene, operating principles | Everyone who's past day 1 |
| 🔴 Layer 3: Advanced Config | Models, memory, crons, streaming, sandboxing | Power users |
| ⚫ Layer 4: Real Setup | My actual production config (sanitized) | The curious |
# Is everything running?
openclaw status
# Deeper diagnostic
openclaw doctor --non-interactive
# Tail logs when something feels off
openclaw logs --tail 200
# Check gateway health
openclaw health
Daily Maintenance Cron
One cron job. Runs at 5 AM. Fixes everything it can.
# Create via OpenClaw's built-in cron system
# In your AGENTS.md or via the cron tool:
# Schedule: 0 5 * * * (5 AM daily)
# Payload: openclaw doctor --fix && openclaw health
After the 355-item audit, these are the security settings that actually matter:
1. Gateway Auth (CRITICAL)
{
gateway: {
auth: {
mode: "token", // Never run without auth
token: "${OPENCLAW_GATEWAY_TOKEN}" // Use env var, never hardcode
},
bind: "loopback", // 127.0.0.1 only
mode: "local" // No external access
}
}
Set OPENCLAW_GATEWAY_TOKEN in ~/.openclaw/.env. Generate it properly:
openssl rand -hex 24
2. Channel Lockdown (CRITICAL)
{
channels: {
telegram: {
enabled: true,
dmPolicy: "pairing", // Only paired users
allowFrom: ["YOUR_TELEGRAM_ID"], // Restrict to your ID
groupPolicy: "allowlist", // No random groups
configWrites: false // No config changes via chat
}
}
}
Get your Telegram ID: message @userinfobot on Telegram.
3. mDNS Discovery (CRITICAL)
{
discovery: {
mdns: { mode: "off" } // Don't broadcast your agent on the network
}
}
If mdns.mode is "on", anyone on your LAN can discover your agent. Turn it off unless you're using multi-node setups.
You add crons for email, calendar, security, content scouting
12+ scheduled LLM calls fire every 5-30 minutes
Every auth profile hits cooldown simultaneously
Your system goes dark for hours
The Fix: Batch into heartbeat or reduce frequency.
| Needs LLM? | Exact timing? | Use |
|---|---|---|
| Yes | Yes | Cron (isolated session) |
| Yes | No | Heartbeat (single batched call) |
| No | Either | launchd/cron (no LLM cost) |
Key settings:
{
agents: {
defaults: {
heartbeat: {
every: "30m", // Minimum 30 min for solo use
activeHours: {
start: "07:00", // Don't burn tokens while sleeping
end: "23:00"
},
target: "last",
ackMaxChars: 120
}
}
}
}
One user reported burning $50/day with a 5-minute heartbeat. For personal use, 30-60 minutes is plenty. Use shorter intervals only during active incident response.
Plan tier matters. Opus is the best model for autonomous reasoning, personality, and complex tasks. If you're on a Pro plan, Sonnet is a perfectly acceptable primary — don't burn free time fighting plan limits. Update your config to reflect reality, not aspiration.
Don't rely on a single model. Configure fallbacks so your agent stays alive when one provider has issues:
{
agents: {
defaults: {
compaction: {
mode: "safeguard",
memoryFlush: {
enabled: true,
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
systemPrompt: "Session nearing compaction. Store durable memories now."
}
}
}
}
}
This ensures important context gets written to files before the session context is summarized and trimmed.
Session Management
{
session: {
reset: {
mode: "daily", // Fresh session daily
atHour: 4, // 4 AM local time
idleMinutes: 720 // Or after 12 hours idle
}
}
}
Timeout:
{
agents: {
defaults: {
timeoutSeconds: 3600 // 1 hour (default is often too short for Codex)
}
}
}
Telegram Streaming & Message Delivery
The default Telegram settings split every paragraph into a separate message bubble. Fix this:
{
channels: {
telegram: {
chunkMode: "length", // NOT "newline" (which splits on every paragraph)
textChunkLimit: 4096, // Telegram's max message size
blockStreaming: true, // Buffer before sending
blockStreamingCoalesce: {
minChars: 200,
maxChars: 4000,
idleMs: 2500 // Wait 2.5s of silence before sending
},
streamMode: "partial",
reactionNotifications: "own",
reactionLevel: "minimal"
}
}
}
Key insight:chunkMode: "newline" sends every paragraph as a separate Telegram message (15+ bubbles for one response). Switch to "length" to only split at the 4096-char Telegram limit.
Trade-off: This requires you to approve EVERY exec command. Great for security, annoying for autonomous work. Consider disabling once you trust your setup.
Cron Jobs (The Right Way)
MECE check before adding ANY cron: Does this overlap with an existing job? Does the heartbeat already cover it?