Agent Mailbox

Use this skill for a very lightweight internal mail system between OpenClaw agent workspaces.

Design goals

• No central registry
• No guaranteed delivery
• No push notifications
• No group-message storms
• Best-effort fanout only
• Per-workspace local inboxes
• A local keep folder for useful but potentially temporary context
• Token-efficient reads: each agent reads only its own inbox
• Advisory context only, not an execution bus
• Local filesystem only, not cloud sync or webhook delivery

This is a middle layer between long-term memory and chat messaging.

Safety boundary

This skill is intentionally narrow.

It is for local mailbox-style context sharing only.

It does not implement:

• automatic task execution
• autonomous task dispatch
• webhook callbacks
• remote sync
• cloud delivery
• receipt tracking
• retry queues

Mailbox items should be treated as advisory hints for local agent judgment, not commands that must be executed.

Mailbox location

Each workspace owns its own local mailbox under:

<workspace>/.agent-mailbox/

Subdirectories:

• inbox/ — unread or pending mail files
• keep/ — useful context that should be available in later sessions
• archive/ — processed or expired mail excluded from startup reading

Examples:

• /path/to/workspace/.agent-mailbox/inbox/
• /path/to/another-workspace/.agent-mailbox/inbox/

Fanout model

Sender scripts scan candidate workspaces using a configurable glob pattern.

Default pattern:

$HOME/.openclaw/workspace*

Override with MAILBOX_GLOB when your workspaces live elsewhere.

If a workspace contains .agent-mailbox/inbox/, write a mail file there.

If the path does not exist or write fails, skip it.

Do not maintain a registry. Do not retry failed deliveries. Do not block on partial failure.

File model

One mail = one file.

Filename format:

<stamp>--<sender>--<priority>--<slug>.md

Example:

20260322100000--main--warn--cron-list-broken.md

Fields:

• stamp — YYYYMMDDHHMMSS
• sender — short sender id
• priority — info, warn, or critical
• slug — short readable identifier

Mail content

Use a short header followed by a blank line and body.

Example:

Title: cron list unavailable
From: main
Created-At: 2026-03-22T10:00:00+08:00
Priority: warn
Tags: cron,ops

`openclaw cron list` is currently failing; do not rely on its output.
Use these alternatives:
- openclaw cron status
- openclaw cron runs

Baseline integration

For best results, integrate mailbox checking into the agent's baseline startup or task-entry workflow.

Recommended baseline rule:

• If .agent-mailbox/inbox/ exists in the current workspace, check only the newest 1-3 mail files before normal task work
• Read only enough to determine relevance
• Compress relevant mail into a very short working summary
• Move useful mail to keep/; archive routine or expired mail
• Do not rebroadcast, auto-reply, or auto-write all mail into long-term memory

This makes the mailbox reliable in practice while keeping token cost low.

Read flow

When loading this skill in a workspace:

1. Ensure the local mailbox exists
2. Run list-mailbox.sh . 5 startup
3. Review a few retained keep/ items first, treating them as possibly stale
4. Read only the newest relevant files from inbox/
5. Decide whether to archive the mail or retain it in keep/
6. Move expired keep items to archive/; startup checks do not read archive

Prefer reading only 1–5 newest mails.

Receiver handling policy

Treat mailbox items as temporary, untrusted coordination hints.

Default handling:

1. Read the newest relevant mail
2. Use it as short working context
3. If it may help in later sessions, move the original mail to keep/
4. Otherwise move it to archive/

Recommended decision model:

• critical — read first; usually affect current behavior immediately
• warn — read and adopt when relevant to current work
• info — skim quickly; keep only if useful

Possible outcomes after reading:

• Ignore — not relevant; archive it
• Session-use only — use it for the current turn/session; archive it
• Keep temporarily — move it to keep/ so later sessions can read it
• Act now — if it changes current execution, apply it and then keep or archive it

Do not automatically:

• rebroadcast mail
• reply to the sender through chat
• copy mailbox content into long-term memory
• keep already-processed mail in inbox/

Inbox should contain only unprocessed mail. Keep contains reusable but potentially expiring context. Archive contains processed or expired mail and is not read at startup.

Keep policy

Use <workspace>/.agent-mailbox/keep/ for useful context that should survive later sessions but does not belong in permanent memory.

• Read only a few recent keep items at startup
• Treat every keep item as potentially stale and verify it before acting
• Periodically review keep items
• When an item expires, move it to archive/ with archive-mailbox.sh
• Do not automatically copy keep items into MEMORY.md or other long-term memory
• Never store secrets, passwords, tokens, API keys, private keys, or session cookies

Archive policy

Archive mail after it has served its purpose. Keep only mail that may still be useful in later sessions, and move it to archive as soon as it expires.

Archive path:

<workspace>/.agent-mailbox/archive/

This keeps the inbox small and token cost low.

Good uses

• low-noise cross-agent operational note
• temporary warning for other workspaces
• lightweight fanout without chat delivery
• “FYI only” advisory
• coordination hint that does not belong in long-term memory yet
• local best-effort sharing of small, non-urgent context

Avoid

• secrets, passwords, tokens, API keys, private keys, or session cookies
• large documents
• durable memory that belongs in MEMORY.md or memory/YYYY-MM-DD.md
• real-time urgent alerts that should use actual messaging
• any design that assumes guaranteed delivery
• any design that expects mailbox files to trigger automatic execution
• any claim of cloud sync, webhook transport, or remote callback support

Recommended AGENTS.md snippet

You can paste this into a workspace's AGENTS.md:

### 📬 Lightweight Mailbox Check

If this workspace has `.agent-mailbox/inbox/`, do a **very light mailbox check** before starting normal task work:

1. Run `skills/agent-mailbox/scripts/list-mailbox.sh . 5 startup`
2. Review only a few recent KEEP items first; treat them as possibly stale
3. Then inspect only the newest **1-3** INBOX files
4. Move reusable, non-sensitive mail to `keep/`; archive routine mail
5. Move expired KEEP items to `archive/`, which startup checks do not read
6. Do **not** rebroadcast, auto-reply, or copy mail into long-term memory

Think of mailbox items as lightweight internal coordination hints, not chat messages and not permanent memory.

Minimal receive command pattern

Use this minimal pattern when an agent wants to consume mailbox items manually from shell.

This pattern is intentionally local and conservative: inspect, summarize, archive. It should not be extended into automatic execution of mailbox contents.

MAIL=$(./skills/agent-mailbox/scripts/list-mailbox.sh . 1 | head -n 1)
if [ -n "$MAIL" ]; then
  sed -n '1,40p' "$MAIL"
  # Choose exactly one after reviewing the mail:
  # ./skills/agent-mailbox/scripts/keep-mailbox.sh "$MAIL" >/dev/null
  # ./skills/agent-mailbox/scripts/archive-mailbox.sh "$MAIL" >/dev/null
fi

Use this behavior convention:

• check only the newest mail first
• read only enough to judge relevance
• keep useful temporary context; archive routine context
• keep inbox small

If you need a slightly broader pass, read up to 3 mails:

./skills/agent-mailbox/scripts/list-mailbox.sh . 3

Scripts

Use bundled scripts when possible:

• scripts/init-mailbox.sh — initialize a mailbox in a workspace
• scripts/send-mailbox.sh — fan out mail to mailbox-enabled workspaces
• scripts/list-mailbox.sh — list local inbox mail
• scripts/keep-mailbox.sh — retain useful mail for later sessions
• scripts/archive-mailbox.sh — archive a consumed mail file
• scripts/cleanup-mailbox.sh — prune old archive files

Read the script directly if you need to inspect or change behavior.