OpenClaw

Install @openmail/openclaw and mail to the agent’s address wakes it. Replies go out in the same thread.

Before you start

OpenClaw 2026.9.2 or newer.
An OpenMail API key from the console. Any scope works.

Install

Install the plugin

openclaw plugins install clawhub:@openmail/openclaw

Reinstalling? Run openclaw plugins enable openmail first; OpenClaw keeps uninstalled plugins disabled.

Add the channel

openclaw channels add --channel openmail --api-key <key>

Picks your inbox, or creates one.

Restart the gateway

openclaw gateway restart
openclaw channels status

Look for OpenMail: enabled, configured, running, connected.

Email the agent and it answers in the thread. Or ask it on your usual chat:

“What’s in the inbox since this morning?”
“Reply to Marc that Thursday works, and cc Jonas.”
“Sign up for the Linear newsletter and give me the confirmation code.”

Something off? openclaw logs | grep openmail.

Modes

Mode	When mail arrives	Good for
`channel`	The agent replies in the thread.	An inbox that is the agent: `support@`
`notify`	The agent tells you on your usual chat and does nothing else.	Your own inbox
`tool`	Nothing. The agent reads the inbox when you ask.	”Sign up for X and tell me the code”

Default is channel. Change it with --mode notify on channels add, or per inbox. Only mail from a person gets a reply. Notifications and verification codes reach the agent as information, so it never answers noreply@. Spam never reaches it.

Who can email the agent

Anyone, by default. Restrict it under Allow/Block List in the console or with the CLI:

openmail policy mode --direction inbound --mode allowlist --inbox-id <id>
openmail policy allow --direction inbound --value marc@example.com --inbox-id <id>

Blocked mail is dropped on the server; the agent never sees it.

Prompt injection

Replies go to the sender OpenMail recorded, not one the message claims. The bundled CLI takes credentials from the channel config and rejects --api-key and --base-url, so a forged mail can’t point the agent at another account. The agent can still start new threads; to stop that, make the inbox’s outbound policy an allowlist.

What the agent can do

The plugin bundles the CLI and a skill that teaches the agent to use it. Every command runs with the channel’s credentials, on the gateway host even if the agent is sandboxed. Keep the --:

openclaw openmail -- threads get --thread-id <id> --json
openclaw openmail --account sales -- send --to a@b.com --body "..."

New threads also work through openclaw message send --channel openmail --to a@b.com "…"; the first line becomes the subject.

Several inboxes

One account per inbox. Each has its own key and can be bound to a different agent.

openclaw channels add --channel openmail --account support --api-key <key> --mailbox-name support
openclaw channels add --channel openmail --account sales   --api-key <key> --mailbox-name sales

One account per pod. Covers every inbox in the pod, including ones the agent creates later. Needs a pod or account key.

openclaw channels add --channel openmail --account outreach --api-key <key> --pod outreach

Each sender gets a conversation per inbox; replies leave from the inbox that received the mail. Set modes per inbox under channels.openmail.inboxes in openclaw.json:

"inboxes": {
  "support@omail.sh": { "mode": "channel" },
  "me@omail.sh": { "mode": "notify" }
}

Attachments

Text from PDF, DOCX, XLSX, PPTX, CSV, and images (OCR) reaches the agent inline, up to 8k characters per file and 24k total. Files without text arrive as files, so a vision model sees the picture; mediaMaxMb caps the total per email (default 20).

Configuration reference

channels add writes channels.openmail in openclaw.json. If you gave it an account key, it stores a narrower pod key instead. No environment variables.

{
  "channels": {
    "openmail": {
      "apiKey": "om_…",
      "inboxId": "…",
      "mode": "channel",
      "accounts": {
        "sales": { "apiKey": { "source": "env", "id": "OPENMAIL_SALES_KEY" }, "inboxId": "…" }
      }
    }
  }
}

Field	Meaning
`apiKey`	Inbox key, or pod key for a pod account. Accepts an OpenClaw SecretRef
`inboxId`	Inbox this account serves
`podId`	Pod this account serves. Replaces `inboxId`
`mode`	`channel` (default), `notify`, or `tool`
`mediaMaxMb`	Staged attachment cap per email. Default `20`; `0` disables
`inboxes`	Per-inbox `mode` overrides, pod accounts only
`accounts`	Named accounts with the fields above. Select with `--account`

channels add flags: --mailbox-name sales creates sales@omail.sh, --display-name sets the sender name, --inbox-id picks an inbox when the key sees several, --pod runs a whole pod, --account names the account, --mode sets the mode.

Upgrading from the CLI bridge

Before @openmail/cli 0.7.0, openmail setup ran a WebSocket bridge as a system service. Those commands are gone.

Stop the old bridge

# Linux
systemctl --user disable --now openmail-openclaw-bridge.service
# macOS
launchctl unload -w ~/Library/LaunchAgents/sh.openmail.openclaw-bridge.plist

Install the plugin

Follow Install with the key from ~/.openclaw/openmail.env.

Remove the old files

Delete ~/.openclaw/openmail.env, ~/.openclaw/skills/openmail/, and the skills.entries.openmail and OpenMail hooks.mappings entries in openclaw.json.

Hermes Agent: the same design as a platform plugin
Sender rules: who can email the agent
Pods: grouping inboxes under one key
Attachments: server-side text extraction

Get started

Core concepts

WebSockets

Webhooks

Guides

Integrations

Best practices

Resources

Security & privacy

Before you start

Install

Modes

Who can email the agent

Prompt injection

What the agent can do

Several inboxes

Attachments

Configuration reference

Upgrading from the CLI bridge

​Before you start

​Install

​Modes

​Who can email the agent

​Prompt injection

​What the agent can do

​Several inboxes

​Attachments

​Configuration reference

​Upgrading from the CLI bridge

​Related

Before you start

Install

Modes

Who can email the agent

Prompt injection

What the agent can do

Several inboxes

Attachments

Configuration reference

Upgrading from the CLI bridge

Related