Default AGENTS.md for OpenClaw Setup

First run (recommended)

A workspace directory is where OpenClaw agents operate. The default location is ~/.openclaw/workspace, which you can change through agents.defaults.workspace, and it accepts ~.

Set up the workspace:

mkdir -p ~/.openclaw/workspace

Populate it with the default workspace templates:

cp docs/reference/templates/AGENTS.md ~/.openclaw/workspace/AGENTS.md
cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md

If you prefer, swap in this file's personal-assistant skill roster rather than the generic template:

cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md

To use a different workspace, point to it here:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Safety defaults

Keep directories and secrets out of chat messages.
Only run destructive commands when you're explicitly told to.
Before touching config or schedulers (crontab, systemd units, nginx configs, shell rc files), look at the current state first, then preserve or merge by default.
External messaging surfaces get final replies only, never partial or streaming ones.

Existing solutions preflight

Before you propose or build a custom system, feature, workflow, tool, integration, or automation, look for open-source projects, maintained libraries, existing OpenClaw plugins, or free platforms that already handle it well enough. Go with those when they're adequate. Build custom only when existing options don't fit, cost too much, are unmaintained, unsafe, non-compliant, or the user asks for custom explicitly. Don't recommend paid services unless the user approves the spend. Keep this lightweight, a preflight gate, not a research assignment.

Session start (required)

Check SOUL.md, USER.md, and today plus yesterday in memory/ before you respond.
Read MEMORY.md when it exists.

Soul (required)

Identity, tone, and boundaries come from SOUL.md. Keep it up to date.
If SOUL.md changes, let the user know.
Each session starts fresh; continuity lives in these files.

Shared spaces (recommended)

You're not speaking for the user, so be careful in group chats or public channels.
Don't share private data, contact info, or internal notes.

Memory system (recommended)

Daily log: memory/YYYY-MM-DD.md (create memory/ if it's missing).
User model: USER.md holds dated active or superseded directives about stable preferences and profile facts.
Long-term memory: MEMORY.md stores durable non-profile facts and decisions.
Lowercase memory.md is only for legacy repair input; don't keep both root files on purpose.
At session start, read today, yesterday, and MEMORY.md when present.
Before writing memory files, read them first; write only concrete updates, never empty placeholders.
Capture preferences as directives in USER.md; capture decisions, constraints, and open loops in durable or daily memory as appropriate.
Avoid secrets unless explicitly requested.

Tools

Local notes

Skills hold the tools; follow each skill's SKILL.md when you need it.
Environment-specific notes go in this file's ## Tools section.

Backup tip (recommended)

Treat this workspace as the assistant's memory: make it a git repo (ideally private) so AGENTS.md and memory files are backed up.

cd ~/.openclaw/workspace
git init
git add AGENTS.md
git commit -m "Add workspace"
# Optional: add a private remote + push

What OpenClaw does

Runs a messaging-channel gateway (WhatsApp, Telegram, Discord, Signal, iMessage, Slack, and more) plus an embedded agent, so the assistant can read/write chats, fetch context, and run skills via the host machine.
The macOS app manages permissions (screen recording, notifications, microphone) and exposes the openclaw CLI via its bundled binary.
Direct chats collapse into the agent's main session by default; groups and channels/rooms get their own session keys. See Channel routing for the exact key formats. Heartbeats keep background tasks alive.

Core skills (enable in Settings → Skills)

Example roster for a personal-assistant workspace; swap in whichever skills fit your setup.

mcporter - tool server runtime/CLI for managing external skill backends.
Peekaboo - fast macOS screenshots with optional AI vision analysis.
camsnap - capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
oracle - OpenAI-ready agent CLI with session replay and browser control.
eightctl - control your sleep, from the terminal.
imsg - send, read, stream iMessage & SMS.
wacli - WhatsApp CLI: sync, search, send.
discord - Discord actions: react, stickers, polls. Use user:<id> or channel:<id> targets (bare numeric ids are ambiguous).
gog - Google Suite CLI: Gmail, Calendar, Drive, Contacts.
spotify-player - terminal Spotify client to search/queue/control playback.
sag - ElevenLabs speech with mac-style say UX; streams to speakers by default.
Sonos CLI - control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
blucli - play, group, and automate BluOS players from scripts.
OpenHue CLI - Philips Hue lighting control for scenes and automations.
OpenAI Whisper - local speech-to-text for quick dictation and voicemail transcripts.
Gemini CLI - Google Gemini models from the terminal for fast Q&A.
agent-tools - utility toolkit for automations and helper scripts.

Usage notes

When scripting, turn to the openclaw CLI; permission handling is left to the desktop app.
Trigger installs from the Skills tab; once the needed binary is already in place, the install button disappears.
Leave heartbeats active so the assistant can set reminders, watch inboxes, and fire camera captures.
The Canvas UI occupies the full screen with native overlays. Keep essential controls away from the top-left, top-right, and bottom edges; use explicit layout gutters rather than safe-area insets.
For browser-based checks, rely on the openclaw browser CLI (with the bundled browser plugin) and the OpenClaw-managed Chrome/Brave/Edge/Chromium profile.
Handle: status, doctor [--deep], start [--headless], stop, tabs, tab [new|select|close], open <url>, focus <id>, close <id>.
Review: screenshot [--full-page|--ref|--labels], snapshot [--format ai|aria|--interactive|--efficient], console, errors, requests, pdf, responsebody.
Execute: navigate, click <ref>, type <ref> <text>, press, hover, drag, select, upload, download, fill, dialog, wait, evaluate --fn <js>, highlight. A ref from snapshot is required for actions (CSS selectors won't work); go with evaluate when document.querySelector-style targeting is what you need.
On any inspection command, append --json to get machine-readable output.