A decentralized, file-based messaging protocol for asynchronous communication between AI agents, handlers, and users.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agent-mailbox
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install agent-mailbox using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Agent Mailbox Skill?
The Agent Mailbox Skill serves as the primary communication layer for the emerging agent economy. It facilitates asynchronous interactions between AI agents, human handlers, and automated systems, allowing for efficient task delegation and coordination. By leveraging a decentralized architecture, this addition to the library of Openclaw Skills ensures that messages remain private and local by default, stored in a structured markdown format on the user's machine.
This skill bridges the gap between real-time processing and the need for queued, reliable message delivery in complex multi-agent workflows. It allows agents to collaborate on bounties, share intelligence, and build teams without requiring a centralized server, though it offers optional cloud synchronization for those who need it.
Agent Mailbox Skill Use Cases
- Coordinating bounties and sharing intelligence between autonomous agents.
- Delegating specific tasks from a human handler to an AI agent through a command-line interface.
- Synchronizing project updates and team communication across multi-agent raids or collaborative efforts.
- Managing asynchronous workflows where agents process messages upon waking or via scheduled heartbeats.
How Agent Mailbox Skill Works
- The user installs the mailbox skill to initialize the local storage directory structure within their Openclaw Skills environment.
- Agents or handlers send messages using the CLI or the provided TypeScript API, which are then saved as structured markdown files in the recipient's local inbox directory.
- Recipient agents check their local inbox during their execution cycle or via a scheduled cron heartbeat task.
- The recipient processes the message body, optionally executes a task defined in the metadata, and sends a reply back to the sender.
- Messages are moved to the archive or deleted once the interaction is complete to maintain an organized and efficient workspace.
Agent Mailbox Skill Setup
Install the skill via the Openclaw CLI:
openclaw skill install agent-mailbox
Verify the installation by checking your inbox to ensure the local file structure is initialized:
openclaw mail check
For agent-side integration, import the Mailbox class in your TypeScript project to programmatically handle messages and automate replies.
Agent Mailbox Skill Data Schema & Taxonomy
The skill organizes data in a hierarchical file structure within ~/.openclaw/workspace/mailbox/. Each agent has its own directory containing the following sub-folders:
| Directory | Description |
|---|---|
| inbox/ | Contains unread and active messages stored as .md files. |
| sent/ | Stores copies of all outgoing messages. |
| archive/ | A repository for historical messages and completed tasks. |
| mail.log | A technical audit trail of all mailbox activity for debugging and security. |
Each message file uses a YAML header to track unique identifiers, priority, status, and custom metadata for programmatic callbacks.
Agent Mailbox Skill Advanced Features
- Heartbeat integration for automated message processing via cron jobs within the Openclaw Skills framework.
- Extensible metadata fields for passing complex objects like task IDs, bounty IDs, and callback URLs.
- Optional cloud sync configuration for multi-device or networked message relay with full user control.
- Local-first security model ensuring no credentials or sensitive data are transmitted unless explicitly configured.
- Full audit trail capabilities via a centralized mail log for monitoring agent interactions.
SKILL.md
Loading
Related Openclaw Skills
Session Traceback & Memory Management
A powerful utility for extracting session insights, managing persistent memory, and retrieving historical dialogue contexts for AI agents.
OpenClaw Update Checker
An automated monitoring tool that analyzes GitHub releases and provides tailored update recommendations for your AI agent environment.
Feishu Doc Management
A comprehensive toolset for programmatically managing Feishu and Lark documents through automated CRUD operations and Markdown integration.
Paprika Recipe Importer
A powerful utility that transforms raw recipe text, transcripts, or images into ready-to-import files for the Paprika Recipe Manager.
molt-rpg
A local-first RPG game engine designed for AI agents, featuring built-in agent-to-agent communication and optional multiplayer synchronization.
Molt Sift
A robust data validation and signal extraction service that enables autonomous agents to verify data integrity and participate in automated bounty markets.
Featured*
