Email Push — IMAP IDLE → OpenClaw Agent → User Notification#

Real-time email monitoring: IMAP IDLE detects new emails, triggers OpenClaw agent to process and notify the user via their active channel.

Security & Permissions#

The agent MUST explicitly inform the user of all actions below and obtain approval before starting installation. Do not proceed without confirmed user consent.

What this skill installs (requires root)#

ActionPath / TargetNotesSystem userimap-watcher (useradd -r)Service runs as this non-root userPython venv/opt/imap-watcher/Isolated env, not system-widepip packageimapclient (inside venv only)Not installed system-wideWatcher script/opt/imap-watcher/imap_watcher.pyCopied from skill directorysystemd unit/etc/systemd/system/imap-watcher.serviceEnabled + started, restarts on bootConfig file/opt/imap-watcher/watcher.confchmod 600, owner imap-watcher onlyLog file/var/log/imap-watcher.logchmod 640, owner imap-watcher

External downloads (requires user awareness)#

WhatFromConditionhimalaya binarygithub.com/pimalaya/himalaya/releases/latest/Only if not already installedMethodcurl | tar into /usr/local/bin/Writes a system binary

Credentials accessed#

CredentialSourceUsageIMAP email passwordProvided by user at install timeIMAP IDLE connectionTelegram botTokenRead from ~/.openclaw/openclaw.jsonRegisters /beemail* commands via Telegram API ( setMyCommands)

The bot token is never stored by this skill.

Auto-reply behaviour#

By default, the agent is instructed not to reply to email senders. This prevents exposing that the system is active and avoids phishing/spam risks. The allow_auto_reply field in watcher.conf controls this:

ValueBehaviourfalse (default)Agent notifies you via Telegram only. Never replies to senders.askAgent asks you for explicit approval via Telegram before replying.trueAgent may reply to senders if it deems appropriate (least safe).

Configured interactively during install. Change anytime with --reconfigure + systemctl restart imap-watcher.

If auto_reply_mode is missing from an existing install, the watcher logs [SECURITY] WARNING on startup and notifies the agent to alert you. The safe default false is applied until you run --reconfigure. It is read once per operation and used only to call api.telegram.org. The agent must inform the user that their bot token will be used to modify the bot's command menu.

Persistence#

This skill installs a persistent background service ( Restart=always, starts on boot). It maintains a continuous IMAP connection. The service runs as the dedicated imap-watcher user, not as root.

Uninstall removes everything: service, systemd unit, /opt/imap-watcher/, log file, system user, and Telegram bot commands.

Install Flow (4 stages)#

Stage 1: Dependencies ( --deps)#

bash

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --deps

Stage 2: Test Connection ( --test)#

bash

echo '{"host":"...","port":993,"ssl":true,"email":"...","password":"..."}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --test

Stage 3: Install (only if Stage 1+2 passed)#

bash

echo '{"host":"...","port":993,"ssl":true,"email":"...","password":"..."}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py

Stage 4: Verify (automatic)#

Other Modes#

Register Bot Commands (after update)#

bash

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --register-commands

Reconfigure (after update)#

After running clawhub update bee-push-email, new config fields may be available. Run:

bash

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --reconfigure

This detects fields missing from your existing /opt/imap-watcher/watcher.conf and asks about each one interactively — without touching your existing values. Restart the service after: systemctl restart imap-watcher.

Force Reinstall#

bash

echo '{...}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --force

Show Config / Uninstall#

bash

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --show
bash /root/.openclaw/workspace/skills/bee-push-email/scripts/uninstall.sh --yes

Telegram Bot Commands#

Click to expand command details

/beemail_status#

1. systemctl is-active imap-watcher + systemctl status imap-watcher --no-pager -l
2. Last 10 log lines: journalctl -u imap-watcher -n 10 --no-pager
3. UID state: cat /opt/imap-watcher/last_seen_uids.json
4. Report: status, uptime, last email, IMAP state

/beemail_start#

1. systemctl start imap-watcher → wait 3s → verify active → show last 5 log lines

/beemail_stop#

1. systemctl stop imap-watcher → verify inactive → report

/beemail_test#

1. Check service active → read target email from config → tell user to send test email
2. Optionally run: setup.py --test

/beemail#

Quick summary: service active? + last email processed + one-liner health

/beemail_reply#

Show current auto-reply mode:

1. Run python3 <skill_dir>/scripts/setup.py --reply-status
2. Report current mode with label: DISABLED / ASK / ENABLED

/beemail_reply_off#

Disable auto-reply immediately:

1. Run python3 <skill_dir>/scripts/setup.py --reply-off
2. Service restarts automatically
3. Confirm: "🔒 Auto-reply DISABLED"

/beemail_reply_ask#

Set approval-required mode:

1. Run python3 <skill_dir>/scripts/setup.py --reply-ask
2. Service restarts automatically
3. Confirm: "❓ Auto-reply set to ASK"

/beemail_reply_on#

Enable auto-reply — warn the user first:

1. Inform user: "⚠️ Enabling auto-reply exposes system activity to all senders including spam/phishing. Confirm?"
2. Only proceed if user confirms
3. Run python3 <skill_dir>/scripts/setup.py --reply-on
4. Service restarts automatically
5. Confirm: "⚠️ Auto-reply ENABLED"

Telegram Bot Commands Troubleshooting#

If /beemail* commands don't appear in the Telegram menu after install:

1. Verify registration: bash

   python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --register-commands
   
   

2. Manual registration via BotFather:

   • Open @BotFather in Telegram
   • Send /setcommands
   • Select your bot
   • Add each command:
     • beemail — Email push status & recent emails
     • beemail_start — Start IMAP email watcher
     • beemail_stop — Stop IMAP email watcher
     • beemail_status — Detailed watcher service status
     • beemail_test — Send test email to verify push

3. If bot token not found: The setup reads botToken from ~/.openclaw/openclaw.json. Check that the Telegram channel is configured.

4. Commands registered but agent doesn't respond: The agent needs this skill installed to handle the commands. Verify with clawhub list.

Troubleshooting#

• Logs: journalctl -u imap-watcher -f
• Status: systemctl status imap-watcher
• Restart: systemctl restart imap-watcher
• Config: /opt/imap-watcher/watcher.conf (JSON, chmod 600)
• State: /opt/imap-watcher/last_seen_uids.json

Architecture#

1. imap_watcher.py maintains persistent IMAP IDLE connection
2. On new email, resolves active OpenClaw session (with 60s cache)
3. Triggers openclaw agent --deliver to process and notify user
4. Uses Himalaya for email operations (read, move, reply)
5. Runs as systemd service as dedicated imap-watcher user with auto-reconnect, exponential backoff, and health checks