🤖max.bota practical guide to working with an AI assistant
5 min read

Under the hood

What OpenClaw is, the moving parts, and how to know which knob to turn when things break. Skip this if you're not running OpenClaw — the concepts in the other pages don't depend on it.

A small mechanical machine with screen and cables

#What OpenClaw is

It's an open-source AI gateway. The layer that:

  • Connects messaging channels (WhatsApp, Signal, Telegram, iMessage, Discord, web chat) to LLM providers
  • Routes requests to Anthropic, OpenAI, Gemini, Ollama, or local models
  • Runs scheduled tasks (cron jobs) and sub-agents
  • Manages sessions, memory, tool calls
  • Hosts the macOS menu-bar app for permissions + system tools

Think of it as the kernel; the assistant is the application running on top. The same kernel can run a different assistant if you wanted (different personality, different memory).

#Where things live

~/.openclaw/                  config + state + secrets root
  workspace/                   your editable workspace
    MEMORY.md, SOUL.md, etc.   "the binder" — loaded on startup
    memory/                    daily logs
    skills/                    plug-in capabilities
    [project dirs]             actual code + apps
  secrets/                     credentials (gitignored, chmod 600)
  config/                      gateway + provider config

/opt/homebrew/lib/node_modules/openclaw/
  docs/                        reference docs (grep when stuck)
  skills/                      built-in skills

#The CLI

openclaw status              # gateway + session health
openclaw cron list           # what's scheduled
openclaw gateway restart     # restart after config changes
openclaw chat                # send a message via terminal
openclaw doctor              # diagnose issues

#Three kinds of sessions

  • Main — your direct chat. Loads MEMORY.md. Persistent.
  • Isolated — short-lived sessions spawned for a specific task (a cron job, a one-shot research dive). Don\'t load MEMORY.md unless told to.
  • Sub-agent — spawned by the main session for parallel work.

#Skills

Plug-in capabilities. Each skill is a folder with a SKILL.md describing what it does + when to invoke it. Examples bundled with OpenClaw:

  • browser-automation — control a real browser
  • notion — read/write Notion pages + DBs
  • github — gh CLI workflows
  • weather — wttr.in forecasts
  • video-frames — extract frames with ffmpeg

Add new skills via clawhub or by dropping a folder into ~/.openclaw/workspace/skills/.

#Provider routing

Provider-agnostic. Anthropic, OpenAI, Gemini, or local models — switch via gateway config or per-session model override.

Tip: route heavy reading (long doc parsing, intel digests) to Gemini 2.5 Pro for its 2M context + lower cost. Route generation + tough reasoning to Claude. Track spend on a dashboard so you know which is burning budget.

#Cron jobs

Two payload kinds:

  • systemEvent — injects text into the main session at a scheduled time. Good for reminders.
  • agentTurn — spawns an isolated session that runs an LLM call. Good for scheduled work like daily briefs.

Inspect via openclaw cron list or a status dashboard.

#When things break

  • openclaw status
  • openclaw doctor
  • tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
  • openclaw gateway restart
  • When in doubt, ask the assistant — it can dig through logs and fix common problems autonomously.

#Docs

  • Official: docs.openclaw.ai
  • Source: github.com/openclaw/openclaw
  • Local install docs: /opt/homebrew/lib/node_modules/openclaw/docs/