malclaw

an opinionated openclaw setup for autonomous coding agents.

this is my personal ai assistant config — it orchestrates claude code and codex agents via tmux, manages task queues, auto-verifies work, and posts updates to discord. built for solo devs / small teams running openclaw on a VPS.

what's in here

├── workspace/
│   ├── AGENTS.md              # agent behavior rules
│   ├── SOUL.md                # personality & tone
│   ├── USER.md.template       # fill in your info
│   ├── IDENTITY.md.template   # bot identity
│   ├── TOOLS.md               # local environment notes
│   ├── FLOW.md                # task orchestration architecture
│   ├── HEARTBEAT.md           # periodic check instructions
│   └── scripts/
│       ├── check-agents.sh    # zero-cost bash cron monitor
│       └── spawn-agent.sh     # spawn claude code in tmux
├── config/
│   └── openclaw.json.template # sanitized config template
├── cron/
│   └── setup.sh               # install cron jobs
└── skills/                    # curated skill set (install via clawhub)

the architecture

three monitoring layers that keep agents productive:

1. openclaw isolated cron (every 5 min) — AI-powered task runner. reads queue, spawns agents, verifies, commits. costs ~$0.02/run.
2. bash cron (every 3 min) — zero-cost monitoring. detects dead tmux sessions, fires system events.
3. heartbeat (every 30 min) — backup layer. checks queue if idle.

single source of truth: tasks/queue.json. no competing state files.

┌─────────────────────────────────────────────────┐
│                   queue.json                     │
│  (single source of truth for all task state)     │
└──────────┬──────────────────────┬───────────────┘
           │                      │
    ┌──────▼──────┐      ┌───────▼────────┐
    │ bash cron   │      │ openclaw cron  │
    │ (3 min)     │      │ (5 min)        │
    │ zero-cost   │      │ AI-powered     │
    │ monitoring  │      │ task runner    │
    └──────┬──────┘      └───────┬────────┘
           │                      │
           │  system event        │  reads queue
           │  on dead agent       │  spawns agents
           ▼                      ▼
    ┌─────────────┐      ┌───────────────┐
    │  heartbeat  │      │ claude code   │
    │  (30 min)   │      │ in tmux       │
    │  backup     │      │               │
    └─────────────┘      └───────────────┘

setup

prerequisites

• openclaw installed and configured
• claude code CLI (claude)
• tmux
• a VPS with 8GB+ RAM (or local machine)

1. clone

git clone git@github.com:MAlshaik/malclaw.git
cd malclaw

2. copy workspace files

# back up your existing workspace
cp -r ~/.openclaw/workspace ~/.openclaw/workspace.bak 2>/dev/null

# copy workspace files (won't overwrite existing)
cp -rn workspace/* ~/.openclaw/workspace/

# set up your identity
cp ~/.openclaw/workspace/USER.md.template ~/.openclaw/workspace/USER.md
cp ~/.openclaw/workspace/IDENTITY.md.template ~/.openclaw/workspace/IDENTITY.md
# edit both with your info

3. configure openclaw

cp config/openclaw.json.template ~/.openclaw/openclaw.json

edit ~/.openclaw/openclaw.json and replace placeholders:

placeholder	what it is	where to get it
YOUR_DISCORD_TOKEN	discord bot token	discord.dev
YOUR_TELEGRAM_BOT_TOKEN	telegram bot token	@BotFather
YOUR_BRAVE_SEARCH_KEY	brave search API	brave.com/search/api
YOUR_MEM0_API_KEY	mem0 memory plugin	mem0.ai
YOUR_GATEWAY_TOKEN	gateway auth	openssl rand -hex 24

4. install cron monitoring

chmod +x cron/setup.sh
./cron/setup.sh

5. set up the task runner

openclaw cron add \
  --name "task-runner" \
  --every "5m" \
  --session isolated \
  --message 'Read ~/.openclaw/workspace/FLOW.md and ~/.openclaw/workspace/tasks/queue.json. Check tmux for agents. If agent finished: verify, commit, update queue. If nothing running and tasks queued: start next. If all done: HEARTBEAT_OK.' \
  --announce

6. create your first task

mkdir -p ~/.openclaw/workspace/tasks
cat > ~/.openclaw/workspace/tasks/queue.json << 'EOF'
{
  "version": 1,
  "lastUpdatedBy": "manual",
  "lastUpdatedAt": "2026-01-01T00:00:00Z",
  "queue": [
    {
      "id": "T0",
      "priority": 0,
      "status": "queued",
      "title": "your first task description here"
    }
  ]
}
EOF

the task runner picks it up on the next cron tick.

how it works

task lifecycle

queued → in-progress → done
                    → failed (retry or skip)

agent spawning

agents run in tmux so they persist if your SSH drops:

tmux new-session -d -s task-name \
  "claude -p 'your prompt' --allowedTools 'Edit,Write,Read,Bash(npx *)' \
  2>&1 | tee /tmp/agent-task-name.log; \
  openclaw system event --mode now --text 'task-name finished'"

the system event at the end wakes the main session to verify and commit.

self-trigger patterns

do: openclaw system event --mode now --text "message"

don't: openclaw agent --deliver ... & (orphans processes)

memory persistence

pre-compaction flush is enabled — the agent writes task state to files before context gets summarized. this prevents amnesia across long sessions.

lessons learned

things i figured out the hard way so you don't have to:

• skip codex for planning — it reads files for 15-30 min without producing plans. plan directly.
• 1 agent at a time on 8GB — can't handle parallel agents + dev server + chrome. serialize.
• isolated cron > heartbeat for tasks — fresh context every run, no compaction amnesia.
• bash cron for monitoring — zero token cost. trigger AI only when something actually happens.
• one state file — competing state files (active.json + queue.json) cause drift. pick one.
• don't trust "build passes" in agent logs — always verify independently.
• claude code buffers output — don't poll the log. check if tmux session is alive and if files changed.
• never background self-triggers — openclaw agent --deliver & orphans. run foreground or use system events.

customization

personality

edit workspace/SOUL.md. default: casual lowercase, no emojis, straightforward.

monitoring frequency

openclaw cron edit <job-id> --every "10m"  # isolated cron
crontab -e  # bash cron interval

add channels

update channel IDs in FLOW.md and the cron job delivery target.

what this isn't

• not a framework — it's a config repo
• not multi-tenant — it's one person's setup
• not magic — you still write the task descriptions

license

MIT