“`html

# Hardware connection topology
Agent Loop
  ├── Vision Input (USB Camera)
  ├── Audio Input (USB Microphone)
  ├── Motor Control (xArm SDK via Ethernet)
  └── State Database (local SQLite for telemetry)

pip install xarm-python-sdk

pip install opencv-python pyaudio numpy

# perception.py
import cv2
import base64
from datetime import datetime

class PerceptionModule:
    def __init__(self, camera_index=0):
        self.cap = cv2.VideoCapture(camera_index)
        self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
        self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
    
    def capture_frame(self):
        ret, frame = self.cap.read()
        if not ret:
            return None
        return frame
    
    def encode_frame_for_agent(self, frame):
        """Convert frame to base64 for OpenClaw context"""
        _, buffer = cv2.imencode('.jpg', frame)
        img_str = base64.b64encode(buffer).decode()
        return f"data:image/jpeg;base64,{img_str}"
    
    def get_perception_state(self):
        """Called each agent cycle"""
        frame = self.capture_frame()
        if frame is None:
            return {"status": "camera_error"}
        
        encoded = self.encode_frame_for_agent(frame)
        return {
            "timestamp": datetime.utcnow().isoformat(),
            "image": encoded,
            "description": "Current visual field from arm-mounted camera"
        }
    
    def cleanup(self):
        self.cap.release()

# motor_control.py
from xarm.wrapper import XArmAPI
import logging

logger = logging.getLogger(__name__)

class MotorController:
    def __init__(self, robot_ip="192.168.1.231"):
        self.arm = XArmAPI(robot_ip)
        self.arm.motion_enable(True)
        self.arm.set_mode(0)  # Position control mode
        self.arm.set_state(0)  # Running state
    
    def move_to_position(self, x, y, z, roll, pitch, yaw):
        """Move arm to Cartesian position"""
        try:
            self.arm.set_position(
                x=x, y=y, z=z,
                roll=roll, pitch=pitch, yaw=yaw,
                speed=200, wait=False
            )
            return {"status": "moving", "target": [x, y, z]}
        except Exception as e:
            logger.error(f"Move failed: {e}")
            return {"status": "error", "message": str(e)}
    
    def open_gripper(self, width=800):
        """Open gripper to specified width (0-850 mm)"""
        try:
            self.arm.set_gripper_position(width)
            return {"status": "gripper_opened", "width": width}
        except Exception as e:
            return {"status": "error", "message": str(e)}
    
    def close_gripper(self):
        """Close gripper fully"""
        return self.open_gripper(width=0)
    
    def get_current_state(self):
        """Return arm position and gripper state"""
        position = self.arm.get_position()
        gripper_state = self.arm.get_gripper_position()
        return {
            "position": {
                "x": position[1][0],
                "y": position[1][1],
                "z": position[1][2],
                "roll": position[1][3],
                "pitch": position[1][4],
                "yaw": position[1][5]
            },
            "gripper_width": gripper_state[1]
        }
    
    def stop(self):
        self.arm.set_state(4)  # Pause state

# agent_config.json
{
  "name": "RoboticArm",
  "model": "gpt-4-vision",
  "system_prompt": "You are controlling a 5-axis robotic arm. You can see the world through a camera. Available actions: move_to_position, open_gripper, close_gripper, get_state. Always check current state before moving. Be cautious with movements.",
  "actions": [
    {
      "name": "move_to_position",
      "description": "Move arm to XYZ coordinates with orientation (roll, pitch, yaw)",
      "parameters": {
        "x": {"type": "number", "description": "X coordinate in mm"},
        "y": {"type": "number", "description": "Y coordinate in mm"},
        "z": {"type": "number", "description": "Z coordinate in mm"},
        "roll": {"type": "number", "description": "Roll in degrees"},
        "pitch": {"type": "number", "description": "Pitch in degrees"},
        "yaw": {"type": "number", "description": "Yaw in degrees"}
      }
    },
    {
      "name": "open_gripper",
      "description": "Open gripper",
      "parameters": {
        "width": {"type": "number", "description": "Gripper width (0-850mm)"}
      }
    },
    {
      "name": "close_gripper",
      "description": "Close gripper fully",
      "parameters": {}
    },
    {
      "name": "get_state",
      "description": "Get current arm position and gripper state",
      "parameters": {}
    }
  ]
}

# main_agent.py
from openclaw import Agent
from perception import PerceptionModule
from motor_control import MotorController
import json

with open('agent_config.json') as f:
    config = json.load(f)

agent = Agent(config)
perception = PerceptionModule()
motor = MotorController()

# Register action handlers
agent.register_action('move_to_position', lambda **kwargs: motor.move_to_position(**kwargs))
agent.register_action('open_gripper', lambda **kwargs: motor.open_gripper(**kwargs))
agent.register_action('close_gripper', lambda: motor.close_gripper())
agent.register_action('get_state', lambda: motor.get_state())

# Main loop
while True:
    # Inject perception state
    perception_data = perception.get_perception_state()
    agent.add_context("current_perception", perception_data)
    
    # Run one decision cycle
    action = agent.decide()
    
    if action:
        print(f"Agent decided: {action['name']} with {action['params']}")
        result = agent.execute_action(action)
        print(f"Result: {result}")

“`html

OpenClaw MEMORY.md: The Complete Guide to Persistent AI Memory

If you’ve been running OpenClaw agents for more than a few sessions, you’ve probably hit the wall: context windows fill up, previous learnings vanish, and your AI restarts from scratch. I spent weeks watching my agents repeat mistakes they’d already solved. That’s when I got serious about MEMORY.md.

This file is the difference between a stateless chatbot and an agent that actually learns. Here’s how I’ve implemented it across production workflows.

How MEMORY.md Actually Works

MEMORY.md isn’t magical. It’s a persistent text file that lives in your agent’s working directory. When your agent initializes, it reads this file. When it learns something valuable, it updates this file. Between sessions, that knowledge persists.

The system works because of two core functions: memory_search and memory_get. Understanding the difference changed how I structure memories.

memory_get retrieves the entire MEMORY.md file. Use this sparingly—it’s a context dump. I call it only during agent initialization or when dealing with context overload recovery.

memory_search performs semantic search across your memory file. This is your workhorse. When your agent needs to recall something specific, search for it by concept, not by filename.

Here’s a real example from my API integration agent:

Agent: "I need to authenticate with the Stripe API"
memory_search("Stripe authentication key management")

Returns:
- Stripe API keys must be injected via environment variables, never hardcoded
- Test keys start with sk_test_, production with sk_live_
- Implement key rotation every 90 days
- Previous failure: hardcoded key in config.yaml caused security audit flag

That search took milliseconds and returned contextual guidance without bloating my token count. That’s the pattern.

Memory Search vs Memory Get: When to Use Each

I made mistakes here. Early on, I called memory_get constantly. Context exploded. Here’s my decision matrix:

Use memory_search when:

• Your agent is executing a specific task and needs related context
• You have more than 5KB of memories accumulated
• You want to avoid loading irrelevant historical data
• Latency matters (which it always does)

Use memory_get when:

• Initializing an agent for the first time in a session
• Your memory file is under 3KB
• You’re doing a complete context reset to prevent drift
• Debugging why the agent made a bad decision

In production, I structure this into the agent’s initialization prompt:

INITIALIZATION SEQUENCE:
1. memory_get() → load all memories
2. Parse into working knowledge
3. For each new task: memory_search(task_context)
4. Execute task
5. memory_update() → store learnings
6. Never call memory_get() during task execution

Preventing Context Bloat: The Real Problem

This is where most people fail. They dump everything into MEMORY.md and watch their context window choke.

I solve this with aggressive archival. Every 30 days, I review my MEMORY.md and run a cleanup:

• Remove duplicate learnings (keep the most specific version)
• Archive superseded information to a separate MEMORY_ARCHIVE.md
• Consolidate vague memories into actionable templates
• Delete anything not referenced in the past 60 days

Here’s what my cleanup script looks like:

#!/bin/bash
# Archive old memories

MEMORY_FILE="MEMORY.md"
ARCHIVE_FILE="MEMORY_ARCHIVE.md"
CUTOFF_DATE=$(date -d "60 days ago" +%s)

# Find entries with timestamps older than cutoff
grep -B2 "last_used:" $MEMORY_FILE | while read line; do
  entry_date=$(echo $line | grep -o '[0-9]\{10\}')
  if [ "$entry_date" -lt "$CUTOFF_DATE" ]; then
    echo "$line" >> $ARCHIVE_FILE
  fi
done

# Regenerate MEMORY.md with only active entries

I also cap my active MEMORY.md at 8KB. When it approaches that, the agent gets an instruction to compress before appending new memories.

Structuring Long-Term vs Daily Memories

Not all memories have equal weight. I separate them:

Long-term memories are principles, patterns, and lessons that rarely change. These include API specifications, architectural decisions, and hard-earned debugging insights. They live in the top section of MEMORY.md with minimal timestamps.

Daily memories are task-specific learnings, recent successes, and current project context. These are timestamped and rotated out frequently.

Here’s my actual MEMORY.md structure:

## LONG-TERM KNOWLEDGE
### Architecture Patterns
- Microservices deployment uses Docker Compose with shared .env
- Database migrations must include rollback steps
- All API responses validated against schema before processing

### Common Pitfalls
- PostgreSQL connection pooling: max 20 connections per instance
- Redis cache invalidation: must include version suffix to prevent stale reads
- File uploads: always validate MIME type server-side, never trust client headers

## DAILY CONTEXT
### Current Project (2024-01-15)
- Building user authentication module for dashboard
- Using Auth0 integration (client_id: [redacted])
- Last blocker: session timeout conflicts with refresh token rotation

### Recent Wins
- Fixed N+1 query on user profiles (implemented batch loading)
- Optimized Docker build from 4m to 1.2m via layer caching

### Active Blockers
- CORS headers not propagating to preflight requests
- Need to test against Safari (Edge case found in QA)

This structure means my agent can quickly distinguish between “this is how the world works” and “this is what I’m working on right now.”

Memory Templates That Actually Work

After dozens of iterations, I’ve settled on templates that compress information efficiently:

Problem-Solution Template:

## PROBLEM: [Clear Problem Statement]
- Symptom: [What you observed]
- Root Cause: [Why it happened]
- Solution: [What worked]
- Prevention: [How to avoid next time]
- Tags: [search-friendly keywords]

API Reference Template:

## API: [Service Name]
- Base URL: [endpoint]
- Auth: [method and required fields]
- Rate Limits: [requests/second]
- Common Errors: [error codes and fixes]
- Last Updated: [date]

Decision Log Template:

## DECISION: [What was decided]
- Context: [Why we needed to decide]
- Options Considered: [alternatives and why rejected]
- Chosen Solution: [what we picked and why]
- Reversible: [yes/no and implications]
- Date: [when decided]

I use these templates religiously. They’re searchable, scannable, and compact. When my agent runs memory_search("database connection timeout"), it finds exactly what it needs in seconds.

Practical Implementation: My Current Setup

Here’s what I actually do at the end of each agent session:

1. Agent completes task
2. Run memory_search() on key topics from the session
3. Identify gaps in existing memories
4. Add new learnings using templates above
5. Check MEMORY.md file size
6. If > 7KB: archive and compress
7. Commit changes with timestamp

I also maintain a checklist before deploying an agent to production:

• MEMORY.md exists and is valid markdown
• No hardcoded secrets or credentials
• Most recent memories are timestamped within 30 days
• Archive file exists with historical context
• memory_search is used at least 3x per major task
• No single memory entry exceeds 200 words

What Changed for Me

Before MEMORY.md discipline, my agents repeated mistakes weekly. With this system, they catch 80% of common errors automatically. More importantly, they compound knowledge—each session makes them marginally better than the last.

The key is treating MEMORY.md as a real database, not a dumping ground. Structure it. Search it. Maintain it. Your future self—and your agent—will thank you.

Frequently Asked Questions

“`html

How to Connect OpenClaw to Telegram, Discord, WhatsApp, and Signal (2026 Guide)

I’ve spent the last three years integrating OpenClaw with every major messaging platform, and I’m going to walk you through exactly what works, what doesn’t, and where you’ll hit walls. This isn’t theoretical—these are the steps I use in production environments.

Why Multi-Channel Matters

Your team doesn’t exist on one platform. DevOps engineers live in Discord. Your CEO checks Telegram. Security teams use Signal. WhatsApp is where compliance documentation somehow always ends up. OpenClaw’s strength is that it can push intelligence to all of them simultaneously while respecting each platform’s constraints.

Telegram: The Easiest Win

Start here. Telegram has the most forgiving API and the fastest iteration cycle.

Step 1: Create Your Bot

• Message BotFather on Telegram (@BotFather)
• Send: /newbot
• Follow prompts. Name it something descriptive like “OpenClaw-Alerts”
• Save your token. It looks like: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Step 2: Configure OpenClaw

Open your OpenClaw config file (typically ~/.openclaw/channels.yaml):

channels:
  telegram:
    enabled: true
    token: "YOUR_BOT_TOKEN_HERE"
    chat_id: "YOUR_CHAT_ID"
    parse_mode: "HTML"
    timeout: 10
    retry_attempts: 3
    rate_limit: 30  # messages per minute

To find your chat_id: send any message to your bot, then run:

curl https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates

Look for the “chat” object’s “id” field.

Step 3: Test and Format

Telegram supports HTML formatting natively. I structure alerts like this:

<b>CRITICAL ALERT</b>
<i>Pod redis-master-0 crashed</i>

Namespace: production
Status: CrashLoopBackOff
Restarts: 7

<code>Error: OOMKilled</code>

Test it:

openclaw test-channel telegram

Rate Limits & Gotchas

• Telegram allows ~30 messages/second to a single chat, but groups are stricter (~1 msg/second in some cases)
• Use message threading (reply_to_message_id) to keep conversations organized
• Buttons and inline keyboards work but add latency—skip them for time-sensitive alerts
• Media uploads are slow; stick to text for monitoring

Discord: Structure for Teams

Discord is where I push detailed alerts. The webhook system is robust, and channel organization prevents alert fatigue.

Step 1: Create a Webhook

• In your Discord server, right-click the target channel
• Edit Channel → Integrations → Webhooks → New Webhook
• Copy the webhook URL. It looks like: https://discordapp.com/api/webhooks/123456789/ABCDefg...

Step 2: Configure OpenClaw

channels:
  discord:
    enabled: true
    webhook_url: "YOUR_WEBHOOK_URL"
    username: "OpenClaw Monitor"
    avatar_url: "https://your-domain.com/openclaw-avatar.png"
    timeout: 15
    retry_attempts: 3
    rate_limit: 10  # messages per minute
    embed_color: 15158332  # red for critical

Step 3: Format with Embeds

Discord’s embed system (rich messages) is where it shines. Here’s a real example:

curl -X POST YOUR_WEBHOOK_URL \
  -H 'Content-Type: application/json' \
  -d '{
    "embeds": [
      {
        "title": "Database Connection Pool Exhausted",
        "description": "Primary RDS instance reaching max connections",
        "color": 15158332,
        "fields": [
          {
            "name": "Instance",
            "value": "prod-db-primary",
            "inline": true
          },
          {
            "name": "Current Connections",
            "value": "499 / 500",
            "inline": true
          },
          {
            "name": "Threshold Exceeded",
            "value": "5 minutes",
            "inline": false
          }
        ],
        "timestamp": "2026-01-15T09:30:00Z"
      }
    ]
  }'

Rate Limits & Gotchas

• Discord rate limits: 10 webhook requests per 10 seconds (per webhook)
• Create separate webhooks for critical vs. non-critical alerts
• Embeds are prettier but slower than plain text—use text for high-volume alerts
• Discord has a 2000-character message limit. Break long outputs into multiple embeds
• Thread support is solid if you need to keep related alerts grouped

WhatsApp: The Enterprise Reality

WhatsApp is trickier. You’re not connecting to WhatsApp directly—you’re using the Meta Business API (formerly WhatsApp Business API). This requires phone number verification and an approved business account.

Step 1: Set Up Business Account

• Go to developers.facebook.com and create an app
• Add WhatsApp product
• Verify a phone number (this becomes your sender ID)
• Save your Phone Number ID and Access Token

Step 2: Configure OpenClaw

channels:
  whatsapp:
    enabled: true
    phone_number_id: "YOUR_PHONE_NUMBER_ID"
    access_token: "YOUR_ACCESS_TOKEN"
    recipient_phone: "+1234567890"  # receiver's number with country code
    timeout: 20
    retry_attempts: 5
    rate_limit: 60  # messages per hour (WhatsApp is strict)
    message_type: "text"  # or "template" for pre-approved messages

Step 3: Send Messages (Text Only)

WhatsApp doesn’t support rich formatting in OpenClaw’s standard integration. Send clean text:

curl -X POST https://graph.instagram.com/v18.0/YOUR_PHONE_NUMBER_ID/messages \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "+1234567890",
    "type": "text",
    "text": {
      "preview_url": true,
      "body": "ALERT: Production database backup failed at 03:45 UTC. Status: Check admin panel."
    }
  }'

Rate Limits & Gotchas

• WhatsApp is the strictest: 1000 messages per day for new accounts, scaling up after review
• You must use pre-approved message templates for batch alerts (compliance requirement)
• Delivery confirmation is slow (5-10 seconds); don’t use for real-time multi-step workflows
• No formatting support—plain text only
• Best used for executive summaries and critical escalations, not continuous monitoring

Signal: Privacy-First Alerts

Signal is the security team’s choice. It has the fewest integrations and the steepest setup, but if you’re handling sensitive data, it’s worth it.

Step 1: Install Signal CLI

brew install signal-cli  # macOS
# or: apt-get install signal-cli  # Linux

Step 2: Register a Number

Signal requires a real phone number. Register it:

signal-cli -u +1234567890 register
signal-cli -u +1234567890 verify VERIFICATION_CODE

Step 3: Configure OpenClaw

channels:
  signal:
    enabled: true
    sender_number: "+1234567890"
    recipient_number: "+0987654321"
    cli_path: "/usr/local/bin/signal-cli"
    timeout: 15
    retry_attempts: 3
    rate_limit: 20  # messages per minute
    encryption: "native"  # Signal handles this automatically

Step 4: Test

signal-cli -u +1234567890 send -m "Test alert from OpenClaw" +0987654321

Rate Limits & Gotchas

• No official API rate limits, but Signal’s network is peer-to-peer—be respectful with volume
• No formatting support; plain text only
• Signal-cli runs as a daemon and can be flaky. Always test integration before relying on it
• Messages are end-to-end encrypted by default. No way to audit delivery on Signal’s end
• Best for: sensitive security alerts to specific individuals, not group broadcasts

Choosing Your Platform Strategy

I use all four, but for different purposes:

• Telegram: Team notifications, DevOps alerts, bots with buttons. Fast iteration.
• Discord: Structured team alerts, rich formatting, thread organization. Best for technical teams.
• WhatsApp: C-suite escalations, compliance notifications, human-in-loop approvals.
• Signal: Security incidents, breach notifications, PII-sensitive alerts.

Troubleshooting Checklist

• Test each channel independently: openclaw test-channel [platform]
• Check token/URL validity before debugging logic
• Monitor OpenClaw logs: tail -f ~/.openclaw/logs/channels.log
• Verify rate limits aren’t silently dropping messages—add logging
• Confirm recipient IDs/numbers/chat IDs are correct (most common error)
• Test formatting in each platform’s native client before integrating

That’s it. You now have the foundation to push OpenClaw intelligence everywhere your team actually works.

Frequently Asked Questions

# OpenClaw on Raspberry Pi 5: Full Setup, Performance, and 24/7 Running Guide

Affiliate Disclosure: As an Amazon Associate, we earn from qualifying purchases. This means we may earn a small commission when you click our links and make a purchase on Amazon. This comes at no extra cost to you and helps support our site.

I’ve spent the last three months running OpenClaw on a Raspberry Pi 5, and I’m going to walk you through exactly how I set it up, what performance looks like, and whether it’s viable for serious 24/7 deployments.

## Why I Chose Raspberry Pi 5 for OpenClaw

The Pi 5 is a solid step up from previous generations. 8GB of RAM, a 2.4GHz quad-core processor, and PCIe 2.0 support make it actually competitive for lightweight server workloads. My primary goal: run OpenClaw continuously without paying $20-50/month for VPS hosting.

The trade-off is clear—you get lower performance but genuine cost savings and full hardware control. Let’s talk real numbers.

## Initial Hardware Setup

I’m using:
– Raspberry Pi 5 (8GB model)
– 512GB NVMe SSD via PCIe adapter
– Official 27W power supply
– Passive aluminum heatsink (no active cooling initially)

The NVMe is essential. The microSD card approach will destroy your durability and performance. Trust me on this.

### Step 1: Flashing the OS

Download Raspberry Pi OS Lite (64-bit) from the official website. I use the Imager tool:

# On your desktop/laptop
# Use Raspberry Pi Imager GUI or:
# macOS/Linux terminal approach:
unzip 2024-03-15-raspios-bookworm-arm64-lite.zip
# Flash using dd or your preferred method

Key settings in Imager before flashing:
– Enable SSH
– Set hostname: `openclawpi`
– Set username/password
– Configure WiFi (or use Ethernet—much more stable)
– Set locale and timezone

I flash directly to the NVMe via USB adapter on my laptop, then boot the Pi with it installed.

## Optimizing the Pi 5 for OpenClaw

### Disable Unnecessary Services

Fresh Raspberry Pi OS includes services you don’t need when running headless:

sudo systemctl disable bluetooth
sudo systemctl disable avahi-daemon
sudo systemctl disable cups
sudo systemctl disable wifi-country.service
sudo systemctl stop bluetooth
sudo systemctl stop avahi-daemon

This freed up roughly 50MB of RAM immediately.

### Update System and Install Dependencies

sudo apt update
sudo apt upgrade -y
sudo apt install -y python3-pip python3-venv git curl wget htop

### Configure GPU Memory Split

Since you’re running headless (no HDMI output), give that memory to the system:

# Edit config.txt
sudo nano /boot/firmware/config.txt

# Find the section: [pi5]
# Add or modify:
gpu_mem=16

This gives you back roughly 128MB for OpenClaw.

## Installing OpenClaw

I’m assuming you have a working OpenClaw installation already. If not, follow the official repository setup.

### Create Dedicated Service User

sudo useradd -m -s /bin/bash openclaw
sudo usermod -aG sudo openclaw

### Clone and Setup

sudo su - openclaw
git clone https://github.com/openclawresource/openclaw.git
cd openclaw
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

### Create Systemd Service

Create `/etc/systemd/system/openclaw.service`:

[Unit]
Description=OpenClaw Service
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw/openclaw
ExecStart=/home/openclaw/openclaw/venv/bin/python main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

Check status:

sudo systemctl status openclaw
sudo journalctl -u openclaw -f  # Live logs

## Performance Benchmarking: Pi 5 vs VPS

I ran identical workloads on both for comparison. Here’s what I measured:

### Test Setup
– 1000 concurrent connections
– 10-minute sustained test
– Monitor CPU, memory, network throughput

### Results

| Metric | Pi 5 (8GB) | Budget VPS (2GB) | Budget VPS (4GB) |
|——–|———–|—————–|—————–|
| CPU Usage | 65-75% | 40-50% | 35-45% |
| Memory Used | 6.2GB | 1.8GB | 2.4GB |
| Avg Latency | 145ms | 78ms | 65ms |
| P95 Latency | 420ms | 210ms | 145ms |
| Network Throughput | 85 Mbps | 150+ Mbps | 150+ Mbps |
| Monthly Cost | ~$8 (electricity) | $3.50 | $6.00 |

Reality check: The Pi 5 handles moderate loads fine, but it sweats under sustained heavy traffic. Latency is higher. For hobby projects, APIs with predictable loads, and monitoring tools—it’s great. For production e-commerce or high-traffic apps, stick with VPS.

Frequently Asked Questions

“`html

OpenClaw SOUL.md Deep Dive: Give Your AI Agent a Real Personality

I’ve been working with OpenClaw for the past six months, and there’s one file that consistently makes the difference between a generic AI assistant and one that actually feels like it belongs in your workflow: SOUL.md.

Most developers treat SOUL.md like a nice-to-have. They’re wrong. This file is your instruction layer, your personality engine, and your behavioral governor all wrapped into one. When configured properly, it transforms how your AI agent responds to tasks, handles edge cases, and represents your brand or team.

Let me show you exactly what SOUL.md controls and how to build one that actually works.

What SOUL.md Actually Does

SOUL.md is the system-level configuration file that sits between your model and your prompts. It doesn’t override the model’s core capabilities—it provides the contextual framework for how those capabilities get expressed.

Think of it this way: the model is a skilled employee. SOUL.md is the company culture document, the style guide, and the role description combined.

Specifically, SOUL.md controls:

• Personality and tone — How formal, casual, technical, or conversational responses should be
• Decision-making framework — What values guide choices when there are multiple valid approaches
• Domain constraints — What the agent should and shouldn’t attempt
• Output formatting — Structure, verbosity, and presentation style
• Error handling — How to respond to ambiguity, missing information, or impossible requests
• Interaction patterns — Whether to ask clarifying questions, make assumptions, or defer to the user

When the model receives a prompt, it processes SOUL.md as context that shapes its entire response generation process. It’s not a filter—it’s a lens.

Model Interpretation and Reality

Here’s what I’ve learned through trial and error: the model interprets SOUL.md through its training patterns. A GPT-4 instance and a Claude instance will internalize the same SOUL.md differently because their underlying models have different semantic spaces.

This means you need to test your SOUL.md against your actual model. A SOUL.md that works perfectly with Claude might feel slightly off with GPT-4, and vice versa.

Best practice: when you write SOUL.md, include concrete examples rather than abstract principles. Instead of “be concise,” write “limit explanations to 2-3 sentences unless the user asks for detail.” The model responds better to specificity.

Also, avoid conflicting instructions. I once had a SOUL.md that said “always ask clarifying questions” and “be decisive and take action without confirmation.” The model got confused and produced inconsistent behavior. The resolution was choosing one primary mode and relegating the other to specific contexts.

Building Your First SOUL.md

The structure I’ve found most reliable follows this template:

# SOUL.md: [Agent Name]

## Core Identity
[2-3 sentences defining who this agent is]

## Primary Role
[What this agent does and doesn't do]

## Communication Style
[Tone, formality, technical level]

## Decision-Making Framework
[What principles guide choices]

## Domain Constraints
[Hard limits on scope and behavior]

## Output Format
[How responses should be structured]

## Error Handling
[How to handle ambiguity or conflicts]

Keep the entire file under 500 words. I’ve seen developers create 2000-word SOUL.md files and wonder why the model seems confused. Brevity forces clarity.

Example 1: Technical Assistant Persona

Here’s a real SOUL.md I use for an agent that helps my development team with architecture decisions:

# SOUL.md: ArchitectAI

## Core Identity
You are ArchitectAI, a systems design consultant with 15 years of production experience across distributed systems, databases, and infrastructure. You value pragmatism over theoretical purity.

## Primary Role
Help engineers evaluate architectural tradeoffs, sanity-check designs before implementation, and troubleshoot production issues. Do NOT write production code or make deployment decisions.

## Communication Style
Technical and direct. Use precise terminology. Assume the user understands fundamental CS concepts. No hand-holding.

## Decision-Making Framework
1. Production stability trumps performance optimization
2. Simpler architectures are preferred unless complexity solves a real problem
3. If it works and performs acceptably, don't redesign it
4. When recommending approaches, always mention the cost in operational complexity

## Domain Constraints
- Do not suggest experimental or unproven technologies
- Do not make claims about performance without supporting reasoning
- Do not recommend architectures you haven't seen work in production

## Output Format
- Lead with your recommendation in one sentence
- List 2-3 tradeoffs
- Provide one example from real systems
- If asked why, explain without being defensive

## Error Handling
If you don't have enough information: "I need to know [specific detail]. Without it, I'm guessing."
If the question is outside your expertise: "This is beyond architecture—talk to [domain specialist]."

This SOUL.md prevents the agent from being overly academic or suggesting unnecessary complexity.

Example 2: Creative Director Persona

For a completely different use case, here’s a SOUL.md for an agent that helps with creative brief development:

# SOUL.md: CreativeDirector

## Core Identity
You are a creative director with experience in advertising, brand strategy, and campaign conceptualization. You combine strategic thinking with imaginative problem-solving.

## Primary Role
Help teams develop compelling creative briefs, brainstorm campaign concepts, and evaluate creative work. You challenge assumptions constructively.

## Communication Style
Conversational but structured. Use vivid language and specific examples. Think out loud; show your reasoning process.

## Decision-Making Framework
1. Authenticity and relevance matter more than novelty
2. Every idea must connect to the brand brief
3. Constraints unlock creativity, not limit it
4. Ask "would this change behavior?" before celebrating an idea

## Domain Constraints
- Do not approve final creative work
- Do not oversell mediocre ideas because they're clever
- Do not ignore strategic context in favor of style

## Output Format
- Start with the core insight or tension you see
- Provide 2-3 directional concepts
- Explain why each works (or doesn't)
- Always include a question back to the user

## Error Handling
If the brief is unclear: "Before I brainstorm, let me confirm: what's the actual change you want to see?"
If an idea feels forced: "I'm not convinced this solves the problem. Let's reframe."

Notice the difference in language and priorities compared to the technical version.

Example 3: Business Operations Persona

For a process-focused agent:

# SOUL.md: OpsCoordinator

## Core Identity
You are an operations coordinator who helps teams standardize processes, identify inefficiencies, and implement systems. You value documentation and consistency.

## Primary Role
Help teams document workflows, identify bottlenecks, and design sustainable processes. Make explicit what's implicit.

## Communication Style
Clear and methodical. Use checklists and structured formats. Assume nothing is obvious until it's written down.

## Decision-Making Framework
1. Document first, optimize second
2. Sustainable processes beat heroic effort
3. If it's not measured, it's not managed
4. Involve the people doing the work

## Domain Constraints
- Do not design processes that require heroic commitment
- Do not oversimplify complex human workflows
- Do not ignore incentives and cultural factors

## Output Format
- Summarize the current state in bullet points
- Identify the top 2 friction points with data if available
- Propose one change with clear before/after metrics
- Request feedback from actual practitioners

## Error Handling
If stakeholders disagree: "Let's map out the different constraints each person is optimizing for."

Practical Implementation Steps

Here’s how I actually deploy SOUL.md:

1. Draft your SOUL.md based on the persona you need
2. Save it in your OpenClaw project directory as SOUL.md (standard naming)
3. Run 5-10 test prompts through your agent and evaluate consistency
4. Adjust language that isn’t landing—be specific, not abstract
5. Test against your actual model provider (Claude, GPT-4, etc.)
6. Document deviations you observe and refine iteratively

The first version won’t be perfect. I usually need 3-4 iterations before an agent feels genuinely cohesive.

What I’ve Learned

SOUL.md isn’t a magic solution. It’s a tool for being intentional about how your AI agent behaves. The effort you invest in writing a clear SOUL.md pays back in consistency, reliability, and reduced prompt engineering overhead.

Start with a persona you need. Make your SOUL.md specific to that context. Test it. Refine it. Then you’ll have an agent that actually feels like part of your team.

# 9 OpenClaw Projects You Can Build This Weekend

I’ve been using OpenClaw for about six months now, and I’ve stopped waiting for the “perfect” project to justify learning it. The truth is, the best way to get comfortable with any automation framework is to build something immediately useful. This weekend, I’m sharing nine projects I’ve actually completed—each doable in a few hours with OpenClaw.

## Why These Projects?

These aren’t contrived examples. They’re things I actually wanted automated. Each one uses OpenClaw’s core strengths: scheduled task execution, HTTP requests, data transformation, and multi-service integration. You’ll need basic Python knowledge and API credentials for whichever services you’re targeting, but nothing exotic.

Let’s get started.

## 1. Reddit Digest Bot

This one delivers a daily email with top posts from your favorite subreddits. I built this first because I was drowning in Reddit notifications.

What You’ll Need

• OpenClaw installed (pip install openclawresource)
• Reddit API credentials from your app registration
• SendGrid API key or similar email service

The Setup

Create a file called `reddit_digest.py`:

import openclawresource as ocr
import requests
import smtplib
from datetime import datetime, timedelta
from email.mime.text import MIMEText

reddit_config = {
    "client_id": "YOUR_REDDIT_ID",
    "client_secret": "YOUR_REDDIT_SECRET",
    "user_agent": "DigestBot/1.0"
}

subreddits = ["python", "learnprogramming", "webdev"]

def fetch_top_posts():
    auth = requests.auth.HTTPBasicAuth(
        reddit_config["client_id"],
        reddit_config["client_secret"]
    )
    
    posts = []
    for sub in subreddits:
        url = f"https://www.reddit.com/r/{sub}/top.json?t=day&limit=5"
        response = requests.get(
            url,
            headers={"User-Agent": reddit_config["user_agent"]},
            auth=auth
        )
        
        if response.status_code == 200:
            data = response.json()
            for post in data["data"]["children"]:
                posts.append({
                    "title": post["data"]["title"],
                    "subreddit": sub,
                    "url": f"https://reddit.com{post['data']['permalink']}",
                    "score": post["data"]["score"]
                })
    
    return sorted(posts, key=lambda x: x["score"], reverse=True)

def build_email_body(posts):
    html = "
Daily Reddit Digest
"
    html += f"
Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}
"
    
    for post in posts[:20]:
        html += f"""
        

            
{post['title']}
            
r/{post['subreddit']} • {post['score']} upvotes
        
        """
    
    return html

@ocr.scheduled(interval="daily", time="08:00")
def send_digest():
    posts = fetch_top_posts()
    body = build_email_body(posts)
    
    msg = MIMEText(body, "html")
    msg["Subject"] = f"Daily Reddit Digest - {datetime.now().strftime('%Y-%m-%d')}"
    msg["From"] = "digest@yourdomain.com"
    msg["To"] = "your-email@example.com"
    
    with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
        server.login("your-email@gmail.com", "YOUR_APP_PASSWORD")
        server.send_message(msg)
    
    return {"status": "sent", "posts_included": len(posts)}

if __name__ == "__main__":
    ocr.run([send_digest])

Deploy It

python reddit_digest.py

The `@ocr.scheduled` decorator handles the timing. OpenClaw will execute `send_digest()` daily at 8 AM.

## 2. Pinterest Auto-Poster

Pin content from your blog automatically. This one saves me 15 minutes every morning.

Quick Implementation

import openclawresource as ocr
import requests
from datetime import datetime

@ocr.scheduled(interval="daily", time="09:00")
def post_to_pinterest():
    pinterest_token = "YOUR_PINTEREST_TOKEN"
    board_id = "YOUR_BOARD_ID"
    
    # Get latest blog post
    blog_url = "https://yourblog.com/api/latest-post"
    blog_response = requests.get(blog_url).json()
    
    pinterest_payload = {
        "title": blog_response["title"],
        "description": blog_response["excerpt"],
        "link": blog_response["url"],
        "image_url": blog_response["featured_image"],
        "board_id": board_id
    }
    
    response = requests.post(
        f"https://api.pinterest.com/v1/pins/?access_token={pinterest_token}",
        json=pinterest_payload
    )
    
    return {"status": "posted", "pin_id": response.json().get("id")}

if __name__ == "__main__":
    ocr.run([post_to_pinterest])

## 3. Blog Publishing Pipeline

Automatically convert Markdown to HTML and publish to your static site generator.

The Workflow

import openclawresource as ocr
import markdown
import os
from pathlib import Path
import yaml
import subprocess

DRAFT_DIR = "./drafts"
PUBLISHED_DIR = "./published"
SITE_REPO = "./my-website"

@ocr.task(trigger="file_created", watch_path="./drafts")
def process_blog_post(file_path):
    md_file = Path(file_path)
    
    # Parse frontmatter
    with open(md_file, 'r') as f:
        content = f.read()
    
    parts = content.split('---')
    metadata = yaml.safe_load(parts[1])
    markdown_content = parts[2]
    
    # Convert to HTML
    html = markdown.markdown(markdown_content, extensions=['tables', 'fenced_code'])
    
    # Create output
    slug = metadata.get('slug', md_file.stem)
    output_path = Path(PUBLISHED_DIR) / f"{slug}.html"
    
    html_template = f"""


    
    


    
{metadata['title']}
    
Published: {metadata.get('date', '')}
    {html}

"""
    
    with open(output_path, 'w') as f:
        f.write(html_template)
    
    # Commit and push
    os.chdir(SITE_REPO)
    subprocess.run(["git", "add", "."])
    subprocess.run(["git", "commit", "-m", f"Publish: {metadata['title']}"])
    subprocess.run(["git", "push"])
    
    return {"published": slug, "file": str(output_path)}

if __name__ == "__main__":
    ocr.run([process_blog_post])

## 4. Expense Tracker with Slack Integration

Log expenses to a database via Slack commands.

import openclawresource as ocr
import sqlite3
from datetime import datetime

DB_PATH = "expenses.db"

@ocr.webhook(path="/slack/expense")
def log_expense(request):
    data = request.json
    user_id = data["user_id"]
    text = data["text"]
    
    # Parse: "20 coffee"
    parts = text.split(" ", 1)
    amount = float(parts[0])
    category = parts[1] if len(parts) > 1 else "other"
    
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    
    cursor.execute("""
        INSERT INTO expenses (user_id, amount, category, date)
        VALUES (?, ?, ?, ?)
    """, (user_id, amount, category, datetime.now()))
    
    conn.commit()
    conn.close()
    
    return {
        "response_type": "in_channel",
        "text": f"Logged ${amount} for {category}"
    }

@ocr.scheduled(interval="weekly", time="monday:09:00")
def weekly_summary():
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    
    cursor.execute("""
        SELECT category, SUM(amount) as total
        FROM expenses
        WHERE date >= date('now', '-7 days')
        GROUP BY category
    """)
    
    results = cursor.fetchall()
    conn.close()
    
    summary = "Weekly Expense Summary:\n"
    for cat, total in results:
        summary += f"{cat}: ${total:.2f}\n"
    
    # Send to Slack
    requests.post(
        "YOUR_SLACK_WEBHOOK",
        json={"text": summary}
    )
    
    return {"summary_sent": True}

if __name__ == "__main__":
    ocr.run([log_expense, weekly_summary])

## 5. Email Summarizer

Parse incoming emails and extract key information.

import openclawresource as ocr
import imaplib
import email
import requests
from email.header import decode_header

IMAP_SERVER = "imap.gmail.com"
EMAIL = "your-email@gmail.com"
PASSWORD = "your-app-password"

@ocr.scheduled(interval="hourly")
def summarize_emails():
    mail = imaplib.IMAP4_SSL(IMAP_SERVER)
    mail.login(EMAIL, PASSWORD)
    mail.select("INBOX")
    
    status, messages = mail.search(None, "UNSEEN")
    email_ids = messages[0].split()
    
    summaries = []
    for email_id in email_ids[-10:]:
        status, msg_data = mail.fetch(email_id, "(RFC822)")
        message = email.message_from_bytes(msg_data[0][1])
        
        subject = decode_header(message["Subject"])[0][0]
        sender = message["From"]
        body = message.get_payload(decode=True).decode()
        
        # Use OpenAI API to summarize
        summary = requests.post(
            "https://api.openai.com/v1/chat/completions",
            headers={"Authorization": f"Bearer {OPENAI_API_KEY}"},
            json={
                "model": "gpt-3.5-turbo",
                "messages": [
                    {"role": "user", "content": f"Summarize this email in one sentence:\n\n{body[:500]}"}
                ]
            }
        ).json()["choices"][0]["message"]["content"]
        
        summaries.append({
            "from": sender,
            "subject": subject,
            "summary": summary
        })
    
    # Store in database or send via webhook
    ocr.log(summaries)
    
    mail.close()
    return {"processed": len(summaries)}

if __name__ == "__main__":
    ocr.run([summarize_emails])

## 6. Daily News Briefing

Aggregate news from multiple sources into one morning email.

import openclawresource as ocr

import requests

from datetime import datetime, timedelta

@ocr.scheduled(interval="daily", time="07:00")

def send_news_briefing():

    newsapi_key = "YOUR_NEWSAPI_KEY"

    sources = ["bbc-news", "techcrunch", "hacker-news"]
    articles = []

    for source in sources:

        response = requests.get(

            "https://newsapi.org/v2/top-headlines",

            params={

                "sources": source,

                "apiKey": newsapi_key,

                "pageSize": 3

            }

        )

        articles.extend(response.json()["articles"])
    html = "
Morning Briefing
"

    for article in articles[:10]:

        html += f"""

{article['title']}
{article['description']}
            Read more
        
        """
    requests.post(

        "https://api.sendgrid.com/v3/mail/send",

        headers={"Authorization": f"Bearer {SENDGRID_API_KEY}"},

        json={

            "personalizations": [{"to": [{"email": "you@example.com"}]}],

            "from": {"email": "briefing@yourdomain.com"},

            "subject": f"Morning Briefing - {datetime.now().strftime('%Y-%m-%d')}",

            "content":
Frequently Asked Questions


What is OpenClaw, and what kind of projects does this article feature?
OpenClaw refers to a specific open-source robotics or DIY hardware platform. The projects typically involve building small, interactive gadgets, robotic arms, or sensor-based systems using the OpenClaw framework, perfect for weekend enthusiasts.


What skill level is required to build these OpenClaw projects?
Many OpenClaw projects are designed to be beginner-friendly, often requiring basic soldering skills and familiarity with simple programming concepts. The "weekend" timeframe suggests accessibility for hobbyists and makers of varying experience levels.


What materials or tools are typically needed to complete these projects?
You'll generally need an OpenClaw development kit or core components, basic hand tools, a soldering iron, and a computer for programming. Specific project requirements will vary, but common DIY electronics supplies are usually sufficient.
🤖 Get the OpenClaw Automation Starter Kit (9) →
Instant download — no subscription needed

			
April 1, 2026