OpenClaw Advanced Configuration Complete Tutorial (2026): AGENTS.md, Memory System, Sub-Agents, Cron Tasks, Skill Development & Multi-Channel Integratio

OpenClaw memorySearch Precision Optimization

• Unstructured Log (Low Hit Rate): "Struggled all day, first did DB migration, then deployed new version, tweaked nginx config..."
• Structured Log (High Hit Rate):
  markdown

  ### [PROJECT:MyApp] Nginx Reverse Proxy Configuration
  - **Conclusion**: Successfully deployed using Nginx reverse proxy
  - **Lesson**: Use `127.0.0.1` instead of `localhost` for upstream (IPv6 issue)
  - **Tags**: `#nginx` `#deploy` `#myapp`

  
  

  Configure memorySearch with Free SiliconFlow bge-m3

  The fastest solution for domestic (China) users: SiliconFlow's bge-m3 vector model is completely free.

  
  

  json

  {
    "memorySearch": {
      "enabled": true,
      "provider": "openai",
      "remote": {
        "baseUrl": "https://api.siliconflow.cn/v1",
        "apiKey": "Your_SiliconFlow_API_Key"
      },
      "model": "BAAI/bge-m3"
    }
  }

  
  

  Why bge-m3? Completely free, excellent bilingual (CN/EN) support, 1024-dimensional vectors offer an optimal balance of precision and performance.
  How to get it: Register at siliconflow.cn → Console → Create API Key.

  
  

  OpenClaw Auto-Memory Maintenance: Preventing Expired Logs from Interfering

  Add this weekly maintenance task to HEARTBEAT.md:

  
  

  markdown

  ## Memory Maintenance (Weekly)
  Read `memory/heartbeat-state.json` and check the `lastMemoryMaintenance` field.
  If >= 7 days have passed:
  1. Read logs from `memory/YYYY-MM-DD.md` for the last 7 days
  2. Extract valuable information into corresponding files (`projects.md`/`lessons.md`)
  3. Compress logs for completed one-time tasks into a single-line conclusion
  4. Delete outdated information
  5. Update `lastMemoryMaintenance` in `memory/heartbeat-state.json` to today

  Create memory/heartbeat-state.json:

  {
    "lastMemoryMaintenance": "2026-01-01"
  }

  3. OpenClaw Sub-Agent Tutorial — Parallel Task Processing

  What are Sub-Agents? What problem do they solve?

  By default, AI operates "single-threaded", finishing one task before starting the next. Sub-agents allow the main AI (main brain) to dispatch independent child processes to handle tasks in parallel. Each sub-agent has its own session and automatically reports results upon completion.

  
  

  Configuration (openclaw.json + AGENTS.md)

  Step 1: Declare usage rules in AGENTS.md

  markdown

  ## Sub-Agents
  If a task is complex or time-consuming, dispatch a sub-agent to execute it.

  ### Model Selection Strategy
  | Tier | Model Alias | Use Case |
  |:---|:---|:---|
  | High | `opus` | Complex architecture design, multi-file refactoring, deep reasoning |
  | Medium | `sonnet` | Writing code, scripts, information organization (Default) |
  | Low | `haiku` | Simple file operations, format conversion, search & summarization |

   Step 2: Configure model aliases in openclaw.json

   {
    "models": {
      "your-provider/claude-opus-4": {"alias": "opus"},
      "your-provider/claude-sonnet-4": {"alias": "sonnet"},
      "your-provider/claude-haiku-4": {"alias": "haiku"}
    }
  }

  How much can Sub-Agents save?

  实测 (Real-world test): Token consumption drops by 60–70%. Most daily operations (searching, summarizing, file ops) don't require the strongest model. Haiku is 10x+ cheaper than Opus and performs identically for web searches or file renames.

  
  

  How to Write Sub-Agent Task Descriptions

  Sub-agents are "zero-context"; they only see the task description you provide. Quality dictates output quality.

  
  

  ❌ Bad: "Review my code"
  ✅ Good:

   markdown

   ## Task: Code Security Review
  ### Objective
  Review all `.js` files in `/root/project/src/`, focusing on API security.
  ### Focus Areas
  1. SQL injection risks
  2. Unvalidated user input
  3. Hardcoded secrets or tokens
  4. API endpoints missing permission checks
  ### Constraints
  - Read-only. Do not modify any files.
  - Ignore `node_modules/` and `test/` directories.
  ### Output Format
  Grade by severity (Critical/Important/Suggestion). For each issue, provide: file path, line number, issue description, fix suggestion.
  ### Result
  Write to `/root/project/SECURITY-REVIEW.md`

   

  Concurrency Limit: Run a maximum of 2 sub-agents simultaneously. 4 will likely trigger API 429 rate limits. Tasks with dependencies (B depends on A's output) must run serially; remind the main AI of dependencies in AGENTS.md.

  
  

  ---

  
  

  4. OpenClaw Cron Task Configuration — Automated Daily News/Weekly Reports/Service Checks

  Heartbeat vs. Cron: When to use which?

  Feature	Heartbeat	Cron
  Precision	~Every 30 minutes (may drift)	Minute-precise (cron expression)
  Execution Env	Runs in main session	Can open independent session
  Model	Uses main brain's model	Can specify a different model
  Best For	Lightweight batch checks	Precise timing, independent tasks

  Choose Heartbeat: Lightweight checks that don't mind drift, require recent chat context.
  Choose Cron: Exact timing required, shouldn't interrupt main chat, want to save costs with a cheaper model, or one-off reminders.

  
  

  Three Schedule Types

  1. at — One-time scheduled (auto-deletes after execution)：

   json

  "schedule": {"kind": "at", "at": "2026-02-23T16:00:00+08:00"}

  2.every — Fixed interval loop:

  json

   

   "schedule": {"kind": "every", "everyMs": 3600000}

  Conversions: 5 min = 300000, 30 min = 1800000, 1 hour = 3600000

  3.cron — Cron expression (most flexible, format: min hour day month weekday):

  json

  
  

  "schedule": {"kind": "cron", "expr": "0 9 * * 1", "tz": "Asia/Shanghai"}

  
  

   

  Common Cron Expressions:

  • 0 9 * * * → Every day at 9:00 AM
  • 0 9 * * 1 → Every Monday at 9:00 AM
  • 0 9,18 * * * → Every day at 9:00 AM & 6:00 PM
  • */30 * * * * → Every 30 minutes
  • 0 0 1 * * → 1st of every month at midnight

  
  

  ⚠️ Most Common Pitfall: Always set the tz field! Without it, it defaults to UTC, so "9 AM" becomes 5 PM Beijing time.

  
  

  Two Execution Modes

  systemEvent (Injects message into main session, ideal for reminders):

  json

  "payload": {"kind": "systemEvent", "text": "Reminder: Meeting in 10 minutes"},
  "sessionTarget": "main"

  
  

   agentTurn (Opens independent session, ideal for operations)

  "payload": {"kind": "agentTurn", "message": "...", "model": "haiku"},
  "sessionTarget": "isolated",
  "delivery": {"mode": "announce"}

  sessionTarget: "main" only pairs with systemEvent. sessionTarget: "isolated" only pairs with agentTurn. Mixing them causes errors.

  
  

  Practical Cron Scenarios (Copy-Paste Ready)

  Scenario 1: Daily Tech News Briefing

   {
    "name": "Daily Briefing",
    "schedule": {"kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai"},
    "payload": {
      "kind": "agentTurn",
      "message": "Search today's top tech and AI news. Summarize into 5 bullet points. Each must include: Title, one-sentence summary, source link.",
      "model": "haiku"
    },
    "sessionTarget": "isolated",
    "delivery": {"mode": "announce"}
  }

  Scenario 2: Hourly Server Health Check (Notify only on failure)

   {
    "name": "Service Check",
    "schedule": {"kind": "every", "everyMs": 3600000},
    "payload": {
      "kind": "agentTurn",
      "message": "Use curl to check if these services are online:\n1. http://localhost:8080\n2. http://localhost:3000\n\nIf all are healthy, DO NOT notify me. Only notify if one is down, stating which service failed and the returned error code.",
      "model": "haiku"
    },
    "sessionTarget": "isolated",
    "delivery": {"mode": "announce"}
  }

   Scenario 3: Weekly Project Report (Every Monday)

   {
    "name": "Weekly Project Report",
    "schedule": {"kind": "cron", "expr": "0 10 * * 1", "tz": "Asia/Shanghai"},
    "payload": {
      "kind": "agentTurn",
      "message": "Read log files in `memory/` from the last 7 days. Generate a weekly report including: Completed tasks, ongoing projects, encountered issues, next week's plan. Keep it concise using bullet points.",
      "model": "sonnet"
    },
    "sessionTarget": "isolated",
    "delivery": {"mode": "announce"}
  }

   Scenario 4: One-off Reminder (N minutes later) Tell the AI directly: "Set a reminder for 20 minutes from now." It will auto-create the task. Manual example:

   {
    "name": "Water Reminder",
    "schedule": {"kind": "at", "at": "2026-02-23T04:20:00Z"},
    "payload": {"kind": "systemEvent", "text": "Reminder: Time to drink water!"},
    "sessionTarget": "main"
  }

   

  Cron Management Commands

  bash

   openclaw cron list               # View all tasks
  openclaw cron runs --id <TaskID> # View execution history
  openclaw cron edit <TaskID> --disable # Disable (recommended over deleting)

   

  5. OpenClaw Skill Development Basics — Teaching AI New Capabilities

  What is a Skill? How does it differ from plugins?

  A Skill is simply a Markdown file that uses natural language to describe "under what conditions, execute these steps." Once the AI reads it, it "learns" the capability. No coding required. Anyone can write one.

  
  

  Directory Structure & Load Priority

  <workspace>/skills/    ← User-created (Highest priority)
  ~/.openclaw/skills/    ← Globally installed
  Built-in skills        ← OpenClaw defaults (Lowest priority)

  Each skill is a directory containing a mandatory SKILL.md:

  skills/
    my-skill/
      SKILL.md
      scripts/  ← Optional, for running scripts

  SKILL.md Structure: description Dictates Trigger Rate

  SKILL.md consists of a YAML frontmatter block and the main content:

  yaml

  ---
  name: weather
  description: >
    Fetch weather information. Triggers when: user asks about weather, temperature, 
    rain, clothing advice, umbrella need, travel plans today, etc.
  ---

  The description directly controls trigger probability. Avoid vague terms like "weather-related". List all possible trigger phrases — the more specific, the better. The main content should include: execution steps, output format templates, and error handling.

  
  

  Step-by-Step: Building an IP Lookup Skill

  Step 1: Create directory

  bash

  mkdir -p ~/.openclaw/workspace/skills/ip-lookup

  
  

  Step 2: Write SKILL.md

  markdown

  ---
  name: ip-lookup
  description: >
    IP address lookup. Triggers when: user requests IP query, IP geolocation, 
    "Where is this IP from?", "Check XX.XX.XX.XX for me", etc.
  ---

  # IP Address Lookup
  ## Steps
  1. Extract the IP address from the user's message.
  2. Call `web_fetch` to access: `http://ip-api.com/json/{IP_ADDRESS}?lang=zh-CN`
  3. Parse the returned JSON data.
  4. Reply using the format below:

  ## Output Format
  IP Lookup Result: {IP}
  Location: {country} {regionName} {city}
  ISP: {isp}
  Timezone: {timezone}

  ## Error Handling
  - API returns `"status": "fail"` → Tell user "Likely an internal/private IP or invalid address."
  - Network timeout → Tell user "Request timed out. Please try again later."

   

  Step 3: Test
  Ask the AI: "Where is 8.8.8.8 from?" If it doesn't trigger, add more trigger phrases to the description.

  
  

  Skills with Scripts (e.g., yt-dlp)

  skills/video-downloader/
    SKILL.md
    scripts/
      download.sh
  

  Reference the script in SKILL.md (use workspace-relative paths):
  

  ## Steps
  1. Extract video URL from user message.
  2. Execute: `bash skills/video-downloader/scripts/download.sh "{VIDEO_URL}"`
  3. Inform user of the saved file location.
  

  Best Practices

  1. Test manually first: Run through the workflow with the AI manually. Confirm it works before packaging as a Skill.
  2. Be specific in steps: Call API to fetch data → Use web_fetch to access https://... → Parse JSON results field
  3. Always include error handling: Without it, the AI will hallucinate when exceptions occur.
  4. Test multiple phrasings: Cover all possible user inputs in description, including CN/EN.
  5. Use ClawHub to save time: clawhub install <skill-slug> installs community-made Skills instantly.

  
  

  ---

  
  

  6. Multi-Channel Integration — Discord & Telegram Simultaneously

  Supported Channels

  Channel	Features	Recommendation
  Discord	Full-featured, supports servers + DMs, emoji reactions, markdown tables	⭐⭐⭐⭐⭐
  Telegram	Lightweight, fast, inline buttons, voice messages, file transfer	⭐⭐⭐⭐⭐
  WhatsApp	Large user base, limited formatting support	⭐⭐⭐
  Signal	End-to-end encrypted, strongest privacy	⭐⭐⭐⭐
  Slack	Ideal for team scenarios	⭐⭐⭐
  WebChat	Built-in web chat, zero config	⭐⭐⭐⭐
  Matrix	Decentralized, self-hosted	⭐⭐⭐⭐

  You can connect multiple channels simultaneously. Message routing is automatic — Discord messages reply to Discord, Telegram to Telegram. No cross-talk.

  
  

  Discord Integration Guide (Fixing MESSAGE CONTENT INTENT)

  1. Create Bot: Discord Developer Portal → "New Application" → Name → Create. Left menu "Bot" → "Reset Token" → Copy Token (shown once!).
  2. Enable Privileged Gateway Intents: 90% of beginners miss this. Without it, the bot won't receive message content. Scroll to "Privileged Gateway Intents" and enable:
     • PRESENCE INTENT
     • SERVER MEMBERS INTENT
     • MESSAGE CONTENT INTENT ← CRITICAL Click Save Changes.
  3. Invite Bot: Left menu "OAuth2" → "OAuth2 URL Generator". Scopes: bot. Bot Permissions: Send Messages, Read Message History, Add Reactions, Use Slash Commands. Copy URL → Open in browser → Select server → Authorize.
  4. Get Server ID: Discord Client → Settings → Advanced → Enable Developer Mode → Right-click server name → "Copy Server ID".
  5. Configure openclaw.json:
     json

  
  

  {
    "channels": {
      "discord": {
        "token": "YOUR_BOT_TOKEN",
        "allowFrom": ["server:YOUR_SERVER_ID"],
        "ackReaction": "🫐"
      }
    }
  }
  

  
  

  1. allowFrom supports: "server:ID", "user:ID", "channel:ID".
     ackReaction: Emoji added immediately upon receiving a message ("Received, processing..."). Use a rare emoji for easy visibility.
  2. Restart & Test: openclaw gateway restart

  
  

  Troubleshooting:

  Symptom	Cause	Fix
  Bot online but unresponsive	MESSAGE CONTENT INTENT not enabled	Enable in Dev Portal & Save
  Bot offline	Invalid token or not started	Verify token, check logs via openclaw status
  Only replies in some channels	Insufficient bot permissions	Ensure Send Messages permission in target channel

  Telegram Bot Configuration

  1. Search @BotFather on Telegram → /newbot → Follow prompts → Copy Token.
  2. Search @userinfobot → Send any message → Get your User ID.
  3. Configure openclaw.json:
     json

  
  

  {
    "channels": {
      "telegram": {
        "token": "YOUR_TELEGRAM_BOT_TOKEN",
        "allowFrom": ["YOUR_USER_ID"]
      }
    }
  }

  Running Discord + Telegram Simultaneously

  {
    "channels": {
      "discord": {
        "token": "DISCORD_TOKEN",
        "allowFrom": ["server:123456789"],
        "ackReaction": "🫐"
      },
      "telegram": {
        "token": "TELEGRAM_TOKEN",
        "allowFrom": ["YOUR_USER_ID"]
      }
    }
  }

  Cross-Platform Format Adaptation

  Format	Discord	Telegram	WhatsApp
  Markdown Tables	✅ Supported	❌ Not supported	❌ Not supported
  Code Blocks	✅ Supported	✅ Supported	⚠️ Limited
  Bold/Italic	✅ Supported	✅ Supported	✅ Supported
  Emoji Reaction	✅ Supported	❌ Not supported	❌ Not supported

  Add this to AGENTS.md for auto-adaptation:

  markdown

  ## Platform Formatting
  - **Discord/Telegram**: Markdown supported. Code blocks use ``` wrapping.
  - **WhatsApp**: Tables unsupported. Replace with bullet lists.
  - **Discord**: Wrap multiple URLs in <> to prevent link preview spam.

  7. openclaw.json Configuration Cheat Sheet

  All configurations go in ~/.openclaw/openclaw.json. Restart gateway after changes: openclaw gateway restart.

  
  

  blockStreaming — Fix Long Response Wait Times

  json

  {
    "agents": {
      "defaults": {
        "blockStreamingDefault": "on",
        "blockStreamingBreak": "text_end",
        "blockStreamingChunk": {"minChars": 200, "maxChars": 1500}
      }
    }
  }

  ackReaction — Instant "Message Received" Feedback

  json

  {
    "channels": {
      "discord": {"ackReaction": "🫐"},
      "telegram": {"ackReaction": "✅"}
    }
  }

  compaction — Prevent Long-Chat Amnesia

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

  Related commands: /compact (preserve key info), /new (start new session), /status (check token usage).

  
  

  Heartbeat Tuning — Prevent Off-Hours Spam

  json

  {
    "agents": {
      "defaults": {
        "heartbeat": {
          "every": "30m",
          "target": "last",
          "activeHours": {"start": "08:00", "end": "23:00"}
        }
      }
    }
  }

  Other Common Configurations

  Config Path	Purpose	Recommended Value
  tools.exec.enabled	Allow shell execution	true
  tools.web.search.enabled	Allow web search	true
  tools.web.search.apiKey	Brave Search API Key (Free)	Get at brave.com/search/api
  tools.media.image.enabled	Allow AI image recognition	true (requires vision model)
  agents.defaults.workspace	Workspace path	"~/.openclaw/workspace"
  channels.discord.maxLinesPerMessage	Max lines per Discord message	17

  ---

  
  

  OpenClaw Advanced Setup Checklist

  Complete the top 5 in under 1 hour for immediate, noticeable improvements:

  
  

  1. ✅ AGENTS.md: Session startup flow + memory rules + safety boundaries (30 min)
  2. ✅ memoryFlush: Enable pre-compaction auto-save to fix amnesia (5 min)
  3. ✅ ackReaction: Configure message-received emoji (1 min)
  4. ✅ blockStreaming: Enable streaming responses (5 min)
  5. ✅ Heartbeat Tuning: Set activeHours to prevent midnight spam (5 min)
  6. ⏱️ memorySearch (bge-m3): Configure SiliconFlow free embedding API (10 min)
  7. ⏱️ Memory Maintenance: Add weekly auto-maintenance to HEARTBEAT.md (10 min)
  8. ⏱️ Model Tiering: Configure aliases + allocation strategy, save 60–70% tokens (15 min)
  9. ⏱️ Cron Tasks: Set up daily briefing / service checks (15 min)
  10. ⏱️ Skill Development: Write your first custom Skill (30 min)
  11. ⏱️ Multi-Channel: Connect Discord or Telegram (30 min)

  
  

  ---

  
  

  FAQ

  Q: Where should I place AGENTS.md?
  A: Workspace root directory, same level as SOUL.md and USER.md. Usually: ~/.openclaw/workspace/AGENTS.md.

  
  

  Q: I enabled memoryFlush but AI still forgets. What now?
  A: Verify softThresholdTokens is high enough (recommend 4000). For critical conversations, manually run /compact preserve: technical decisions, user preferences to force retention.

  
  

  Q: My Cron task isn't triggering. Why?
  A: 99% of the time, it's a timezone issue — missing the tz field causes UTC execution. Also verify delivery.mode is set to "announce", otherwise tasks run silently.

  
  

  Q: My Skill is written but the AI won't trigger it.
  A: Check if the description covers your exact trigger phrases. Include both CN and EN variants (e.g., "查IP" and "IP lookup").

  
  

  Q: Discord Bot is online but receives no messages.
  A: Almost certainly MESSAGE CONTENT INTENT is disabled. Return to Discord Developer Portal → Bot → Privileged Gateway Intents → Enable MESSAGE CONTENT INTENT → Save Changes.

  
  

  Q: Will messages cross-talk if I run multiple channels?
  A: No. OpenClaw logs the source channel for each message. Discord replies stay on Discord, Telegram on Telegram.

  
  

  Q: How do Sub-Agents save money?
  A: Define model tiers in AGENTS.md: Haiku for search/summary, Sonnet for coding, Opus only for complex reasoning. Most tasks fall into the Haiku tier, reducing token usage by 60–70% in practice.