test-repo/openclaw-tips-tricks-guide.md

# OpenClaw Tips, Tricks, and Usage Patterns

*A comprehensive guide compiled from official documentation, community resources, and real-world examples.*

**Last Updated:** February 21, 2026  
**Document Version:** 1.0

---

## Table of Contents

1. [Introduction](#introduction)
2. [Best Practices and Workflows](#best-practices-and-workflows)
3. [Tips for Beginners](#tips-for-beginners)
4. [Tips for Advanced Users](#tips-for-advanced-users)
5. [Creative Use Cases](#creative-use-cases)
6. [Integration Examples](#integration-examples)
7. [Community Insights](#community-insights)
8. [Troubleshooting Quick Reference](#troubleshooting-quick-reference)
9. [Resources and Attribution](#resources-and-attribution)

---

## Introduction

OpenClaw is a **self-hosted AI assistant gateway** that connects your favorite chat apps—WhatsApp, Telegram, Discord, iMessage, Slack, and more—to AI coding agents. It runs on your own hardware, giving you complete control over your data while providing always-available AI assistance.

### Key Differentiators

- **Self-hosted**: Runs on your hardware, your rules
- **Multi-channel**: One Gateway serves multiple messaging platforms simultaneously
- **Agent-native**: Built for coding agents with tool use, sessions, memory, and multi-agent routing
- **Open source**: MIT licensed, community-driven

---

## Best Practices and Workflows

### 1. Heartbeat vs Cron: When to Use Each

Understanding when to use heartbeat checks versus cron jobs is crucial for efficient automation.

| Use Case | Recommended | Why |
|----------|-------------|-----|
| Check inbox every 30 min | Heartbeat | Batches with other checks, context-aware |
| Send daily report at 9am sharp | Cron (isolated) | Exact timing needed |
| Monitor calendar for upcoming events | Heartbeat | Natural fit for periodic awareness |
| Run weekly deep analysis | Cron (isolated) | Standalone task, can use different model |
| Remind me in 20 minutes | Cron (main, `--at`) | One-shot with precise timing |
| Background project health check | Heartbeat | Piggybacks on existing cycle |

**Decision Flowchart:**
```
Does the task need to run at an EXACT time?
  YES → Use cron
  NO  → Continue...

Does the task need isolation from main session?
  YES → Use cron (isolated)
  NO  → Continue...

Can this task be batched with other periodic checks?
  YES → Use heartbeat (add to HEARTBEAT.md)
  NO  → Use cron
```

**Source:** [OpenClaw Documentation - Cron vs Heartbeat](https://docs.openclaw.ai/automation/cron-vs-heartbeat)

### 2. Memory Management Best Practices

OpenClaw memory is **plain Markdown in the agent workspace**. Files are the source of truth.

**Default Memory Structure:**
- `memory/YYYY-MM-DD.md` - Daily log (append-only), read today + yesterday at session start
- `MEMORY.md` - Curated long-term memory (load only in main, private sessions)

**When to Write Memory:**
- Decisions, preferences, and durable facts → `MEMORY.md`
- Day-to-day notes and running context → `memory/YYYY-MM-DD.md`
- When someone says "remember this" → Write it immediately (don't keep in RAM)
- If you want something to stick, **ask the bot to write it**

**Pro Tip:** Memory is limited—if you want to remember something, WRITE IT TO A FILE. "Mental notes" don't survive session restarts. Files do.

**Source:** [OpenClaw Documentation - Memory](https://docs.openclaw.ai/concepts/memory)

### 3. Secure DM Mode for Multi-User Setups

**Security Warning:** If your agent can receive DMs from multiple people, enable secure DM mode to prevent context leakage between users.

**The Problem:**
- Alice messages about a private topic (e.g., medical appointment)
- Bob asks "What were we talking about?"
- With default settings, both share the same session context

**The Fix:**
```json5
{
  session: {
    dmScope: "per-channel-peer",  // Isolate DM context per channel + sender
  },
}
```

**When to Enable:**
- You have pairing approvals for more than one sender
- You use a DM allowlist with multiple entries
- You set `dmPolicy: "open"`
- Multiple phone numbers or accounts can message your agent

**Source:** [OpenClaw Documentation - Session Management](https://docs.openclaw.ai/concepts/session)

### 4. Configuration Organization

**Minimal Config (Single User):**
```json5
{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
```

**Recommended Starter:**
```json5
{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}
```

**Source:** [OpenClaw Documentation - Configuration Examples](https://docs.openclaw.ai/gateway/configuration-examples)

---

## Tips for Beginners

### 1. Getting Started Fast

1. **Install OpenClaw:**
   ```bash
   npm install -g openclaw@latest
   ```

2. **Run the Onboarding Wizard:**
   ```bash
   openclaw onboard --install-daemon
   ```

3. **Pair WhatsApp and Start Gateway:**
   ```bash
   openclaw channels login
   openclaw gateway --port 18789
   ```

**Time to Setup:** Usually 5-15 minutes

**Source:** [OpenClaw Documentation - Quick Start](https://docs.openclaw.ai)

### 2. Essential CLI Commands to Know

```bash
# Check status
openclaw status

# View and manage sessions
openclaw sessions --json
openclaw sessions --active 30  # Last 30 minutes

# Check gateway health
openclaw gateway status
openclaw doctor  # Diagnose issues

# View logs
openclaw logs --follow

# Send a test message
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

# Talk to the assistant
openclaw agent --message "Ship checklist" --thinking high
```

### 3. First-Time Configuration Tips

- **Start simple:** Use minimal config, then expand
- **Enable pairing:** Unknown senders receive a pairing code before the bot processes their message
- **Use mention gating in groups:** Require `@openclaw` mention to avoid spam
- **Set up daily memory files:** Ask the agent to write important information to memory

### 4. Resetting Sessions

When conversations get off track:
- Send `/new` or `/reset` to start a fresh session
- Use `/new <model>` to switch models (e.g., `/new opus`)
- Sessions auto-reset daily at 4:00 AM by default

---

## Tips for Advanced Users

### 1. Multi-Agent Routing

Route inbound channels/accounts/peers to isolated agents with separate workspaces:

```json5
{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      { id: "coding", workspace: "~/.openclaw/coding-agent" },
      { id: "personal", workspace: "~/.openclaw/personal-agent" },
    ],
  },
  routing: {
    rules: [
      { channel: "telegram", account: "work", agent: "coding" },
      { channel: "whatsapp", agent: "personal" },
    ],
  },
}
```

**Source:** [OpenClaw Documentation - Multi-Agent](https://docs.openclaw.ai/concepts/multi-agent)

### 2. Model Failover Configuration

Set up automatic fallbacks when primary models fail:

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
    },
  },
}
```

**Source:** [OpenClaw Documentation - Model Failover](https://docs.openclaw.ai/concepts/model-failover)

### 3. Advanced Cron Scheduling

**Daily Morning Briefing:**
```bash
openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"
```

**One-Shot Reminder:**
```bash
openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run
```

**Source:** [OpenClaw Documentation - Cron Jobs](https://docs.openclaw.ai/automation/cron-jobs)

### 4. Skills Development

Skills are **AgentSkills-compatible** folders with `SKILL.md` files. Load locations (in precedence order):
1. `<workspace>/skills` (highest)
2. `~/.openclaw/skills`
3. Bundled skills (lowest)

**Install from ClawHub:**
```bash
clawhub install <skill-slug>
clawhub update --all
```

**Skill Format:**
```markdown
---
name: my-custom-skill
description: Does something useful
metadata:
  { "openclaw": { "requires": { "bins": ["node"], "env": ["API_KEY"] } } }
---

Instructions for the agent on how to use this skill...
```

**Source:** [OpenClaw Documentation - Skills](https://docs.openclaw.ai/tools/skills)

### 5. Canvas and A2UI Integration

The Canvas panel provides a visual workspace for HTML/CSS/JS and A2UI:

```bash
# Present canvas
openclaw nodes canvas present --node <id>

# Navigate to content
openclaw nodes canvas navigate --node <id> --url "/"

# Evaluate JavaScript
openclaw nodes canvas eval --node <id> --js "document.title"

# Capture snapshot
openclaw nodes canvas snapshot --node <id>

# Push A2UI content
openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
```

**Source:** [OpenClaw Documentation - Canvas](https://docs.openclaw.ai/platforms/mac/canvas)

### 6. Voice Wake Configuration

Voice wake words are **global** (owned by the Gateway), stored at:
- `~/.openclaw/settings/voicewake.json`

```json
{ "triggers": ["openclaw", "claude", "computer"], "updatedAtMs": 1730000000000 }
```

Each device keeps its own enabled/disabled toggle while sharing the global trigger list.

**Source:** [OpenClaw Documentation - Voice Wake](https://docs.openclaw.ai/nodes/voicewake)

---

## Creative Use Cases

### From the Community Showcase

#### 1. PR Review → Telegram Feedback
**By:** @bangnokia  
**Flow:** OpenCode finishes change → opens PR → OpenClaw reviews diff → replies in Telegram with suggestions and merge verdict

#### 2. Wine Cellar Skill
**By:** @prades_maxime  
**Flow:** Asked for local wine cellar skill → requests CSV export + storage location → builds/tests skill (962 bottles)

#### 3. Tesco Shop Autopilot
**By:** @marchattonhere  
**Flow:** Weekly meal plan → regulars → book delivery slot → confirm order (no APIs, just browser control)

#### 4. SNAG Screenshot-to-Markdown
**By:** @am-will  
**Flow:** Hotkey screen region → Gemini vision → instant Markdown in clipboard  
**GitHub:** https://github.com/am-will/snag

#### 5. Multi-Agent Content Factory
**By:** Community  
**Flow:** Run multi-agent content pipeline in Discord — research, writing, and thumbnail agents in dedicated channels

**Source:** [OpenClaw Showcase](https://docs.openclaw.ai/start/showcase)

### From Awesome OpenClaw Use Cases

#### Social Media & Content
- **Daily Reddit Digest:** Summarize curated subreddits based on preferences
- **Daily YouTube Digest:** Get summaries of new videos from favorite channels
- **X Account Analysis:** Qualitative analysis of your X/Twitter account
- **Multi-Source Tech News:** Aggregate from 109+ sources (RSS, Twitter, GitHub, web search)

#### Productivity
- **Autonomous Project Management:** Multi-agent projects using STATE.yaml pattern
- **Phone-Based Personal Assistant:** Access AI via voice calls/SMS
- **Inbox De-clutter:** Summarize newsletters and send digests
- **Personal CRM:** Auto-discover and track contacts from email/calendar
- **Second Brain:** Text anything to remember, search via Next.js dashboard

#### Infrastructure
- **Self-Healing Home Server:** Always-on infrastructure agent with SSH access and automated cron jobs
- **n8n Workflow Orchestration:** Delegate API calls to n8n workflows via webhooks

**Source:** [Awesome OpenClaw Use Cases](https://github.com/hesamsheikh/awesome-openclaw-usecases)

---

## Integration Examples

### 1. n8n Workflow Orchestration

Delegate API calls to n8n workflows—the agent never touches credentials:

```bash
# OpenClaw calls n8n webhook
openclaw agent --message "Trigger n8n workflow to add user to Mailchimp"
```

Benefits:
- Visual workflow builder
- Lockable integrations
- No API keys in agent context

### 2. Browser Automation

```bash
# Check browser status
openclaw browser status

# Start browser
openclaw browser start --browser-profile openclaw

# Chrome extension relay (for taking over existing tabs)
openclaw browser profiles
```

### 3. Node Integration (iOS/Android)

Pair mobile nodes for camera, location, and screen capture:

```bash
# List paired nodes
openclaw nodes status

# Take camera snapshot
openclaw nodes camera_snap --node <id> --facing front

# Start screen recording
openclaw nodes screen_record --node <id> --duration 30s

# Get location
openclaw nodes location_get --node <id>
```

### 4. Webhook Integration

```json5
{
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        deliver: true,
        channel: "last",
      },
    ],
  },
}
```

### 5. Custom Model Providers

```json5
{
  models: {
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}
```

---

## Community Insights

### Recommended Model Configuration

**From the community and docs:**
- **Recommended:** Anthropic Pro/Max ($100/$200) + Opus 4.6 for long-context strength and prompt-injection resistance
- **Fallback chain:** Claude Sonnet 4.5 → Claude Opus 4.6 → GPT-5.2

### Security Best Practices

1. **Always use pairing** for unknown senders (`dmPolicy: "pairing"`)
2. **Approve with:** `openclaw pairing approve`
3. **Audit regularly:** `openclaw security audit`
4. **Review third-party skills** before enabling (treat as untrusted code)
5. **Use sandboxed runs** for untrusted inputs

### Popular Channels (in order of community usage)

1. **Telegram** - Easy bot setup, great for beginners
2. **WhatsApp** - Most personal, requires phone pairing
3. **Discord** - Great for multi-user/group collaboration
4. **Slack** - Enterprise/team workflows
5. **iMessage** - Requires macOS (BlueBubbles recommended)
6. **Signal** - Privacy-focused

### Development Workflow Tips

1. **Use `openclaw doctor`** to diagnose issues
2. **Check logs with** `openclaw logs --follow`
3. **Test skills locally** before deploying
4. **Use isolated sessions** for heavy tasks
5. **Set up heartbeat** for routine monitoring instead of multiple cron jobs

---

## Troubleshooting Quick Reference

### No Replies from Bot

```bash
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow
```

**Common causes:**
- Pairing pending for DM senders
- Group mention gating (`requireMention`)
- Channel/group allowlist mismatches

### Gateway Won't Start

```bash
openclaw gateway status
openclaw doctor
openclaw logs --follow
```

**Common causes:**
- `gateway.mode` not set to `local`
- Port conflict (EADDRINUSE)
- Non-loopback bind without auth

### Cron/Heartbeat Not Running

```bash
openclaw cron status
openclaw cron list
openclaw system heartbeat last
```

**Common causes:**
- Cron scheduler disabled
- Outside active hours window
- Invalid account ID for delivery target

### Browser Tool Fails

```bash
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw doctor
```

**Common causes:**
- Chrome not found at configured path
- Extension relay not attached (for Chrome profile)

**Source:** [OpenClaw Documentation - Troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting)

---

## Resources and Attribution

### Official Documentation

- **Main Documentation:** https://docs.openclaw.ai
- **Documentation Index:** https://docs.openclaw.ai/llms.txt
- **GitHub Repository:** https://github.com/openclaw/openclaw
- **Vision Document:** https://github.com/openclaw/openclaw/blob/main/VISION.md

### Community Resources

- **Discord Community:** https://discord.gg/clawd
- **Awesome OpenClaw Skills:** https://github.com/VoltAgent/awesome-openclaw-skills
- **Awesome OpenClaw Use Cases:** https://github.com/hesamsheikh/awesome-openclaw-usecases
- **GitHub Topics:** https://github.com/topics/openclaw

### Key Contributors and Sources

- **OpenClaw Team:** Core platform development and documentation
- **VoltAgent:** Awesome OpenClaw Skills curation
- **@hesamsheikh:** Awesome OpenClaw Use Cases compilation
- **Community Showcase Contributors:** @bangnokia, @prades_maxime, @marchattonhere, @am-will, @kitze, and many others

### Videos and Tutorials

- **Full Setup Walkthrough:** https://www.youtube.com/watch?v=SaWSPZoPX34 (by VelvetShark)
- **Showcase Videos:** https://www.youtube.com/watch?v=mMSKQvlmFuQ, https://www.youtube.com/watch?v=5kkIJNUGFho

### Related Projects

- **Cherry Studio:** AI productivity studio with OpenClaw integration
- **1Panel:** Linux server management with OpenClaw support
- **Umbrel:** Home server OS with OpenClaw app
- **MimiClaw:** Run OpenClaw on a $5 chip (no OS, no Node.js)

---

## License and Usage

This document is a compilation of publicly available information from OpenClaw documentation and community resources. All source materials are attributed above.

OpenClaw itself is released under the **MIT License**.

---

*Document compiled by OpenClaw Research Agent - February 2026*

*For the latest information, always refer to the official documentation at https://docs.openclaw.ai*