Default AGENTS.md: OpenClaw Agent Setup

First run (recommended)

A workspace directory is used by OpenClaw agents. The default location is ~/.openclaw/workspace (adjustable through agents.defaults.workspace, with ~ being supported).

Set up the workspace:

mkdir -p ~/.openclaw/workspace

Transfer the default workspace templates into it:

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

If desired, replace the generic template with this file's personal-assistant skill roster:

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

Optionally, target a different workspace:

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

Safety defaults

Avoid exposing directories or secrets in chat.
Refrain from running destructive commands unless specifically requested.
Before modifying configurations or schedulers (such as crontab, systemd units, nginx configs, or shell rc files), review the current state first and default to preserving or merging changes.
Do not transmit partial or streaming responses to external messaging platforms; only send completed replies.

Existing solutions preflight

When considering a custom system, feature, workflow, tool, integration, or automation, first look for open-source projects, maintained libraries, existing OpenClaw plugins, or free platforms that already address the need adequately. Use those when they suffice. Only build custom solutions if existing options are unsuitable, too costly, unmaintained, unsafe, non-compliant, or if the user explicitly requests a custom approach. Avoid suggesting paid services unless the user has approved spending. Keep this process lightweight, acting as a quick preflight check rather than a full research task.

Session start (required)

Prior to responding, read SOUL.md, USER.md, and the entries for today and yesterday in memory/.
When MEMORY.md is available, read it as well.

Soul (required)

SOUL.md establishes identity, tone, and boundaries. Ensure it stays up to date.
Notify the user if you modify SOUL.md.
Each session starts with a fresh instance; continuity is maintained through these files.

Shared spaces (recommended)

You do not speak for the user; exercise caution in group chats or public channels.
Refrain from sharing private data, contact information, or internal notes.

Memory system (recommended)

Daily log: memory/YYYY-MM-DD.md (create memory/ if it does not exist).
Long-term memory: MEMORY.md for durable facts, preferences, and decisions.
The lowercase memory.md is only for legacy repair input; do not intentionally keep both root files.
At the start of a session, read today's and yesterday's logs plus MEMORY.md when present.
Before writing to memory files, read them first; only record concrete updates, never empty placeholders.
Capture: decisions, preferences, constraints, and open loops.
Avoid storing secrets unless explicitly requested.

Tools and skills

Tools are organized within skills; consult each skill's SKILL.md when you need to use it.
Keep environment-specific details in TOOLS.md (notes intended for skills).

Backup tip (recommended)

Treat this workspace as the assistant's memory: initialize it as a git repository (preferably private) so that 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

Acts as a messaging channel gateway (supporting WhatsApp, Telegram, Discord, Signal, iMessage, Slack, and others) along with an embedded agent, enabling the assistant to read and write chats, retrieve context, and execute skills through the host machine.
The macOS app handles permissions (screen recording, notifications, microphone) and provides the openclaw CLI through its bundled binary.
Direct chats default to collapsing into the agent's main session; groups and channels or rooms receive their own session keys. Refer to Channel routing for the exact key formats. Heartbeats keep background tasks active.

Core skills (enable in Settings → Skills)

Example roster for a personal-assistant workspace; substitute skills as needed for your setup.

mcporter - tool server runtime or CLI for managing external skill backends.
Peekaboo - fast macOS screenshots with optional AI vision analysis.
camsnap - capture frames, clips, or motion alerts from RTSP or ONVIF security cameras.
oracle - OpenAI-ready agent CLI with session replay and browser control.
eightctl - control your sleep from the terminal.
imsg - send, read, and stream iMessage and SMS.
wacli - WhatsApp CLI: sync, search, and send.
discord - Discord actions: react, stickers, and polls. Use user:<id> or channel:<id> targets (bare numeric IDs are ambiguous).
gog - Google Suite CLI: Gmail, Calendar, Drive, and Contacts.
spotify-player - terminal Spotify client for searching, queuing, and controlling playback.
sag - ElevenLabs speech with a macOS-style say UX; streams to speakers by default.
Sonos CLI - control Sonos speakers (discovery, 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

For scripting tasks, the openclaw CLI is the recommended choice, while permission management is handled by the desktop application.

Installations are performed through the Skills tab; once a required binary is already installed, the install button becomes hidden.

Heartbeats should remain enabled to allow the assistant to schedule reminders, monitor inboxes, and trigger camera captures.

The Canvas UI operates full-screen with native overlays. Critical controls must not be placed at the top-left, top-right, or bottom edges; instead, use explicit layout gutters rather than relying on safe-area insets.

For browser-based verification, use the openclaw browser CLI (which includes the browser plugin) together with the OpenClaw-managed Chrome, Brave, Edge, or Chromium profile.

Manage: status, doctor [--deep], start [--headless], stop, tabs, tab [new|select|close], open <url>, focus <id>, close <id>.

Act: navigate, click <ref>, type <ref> <text>, press, hover, drag, select, upload, download, fill, dialog, wait, evaluate --fn <js>, highlight. Each action requires a ref obtained from snapshot (CSS selectors are not valid for actions); use evaluate when document.querySelector-style targeting is needed.

To get machine-readable output from any inspection command, add --json.