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)

Action	Path / Target	Notes
System user	INLINECODE0 (useradd -r)	Service runs as this non-root user
Python venv

External downloads (requires user awareness)

What	From	Condition
INLINECODE7 binary	INLINECODE8	Only if not already installed
Method

curl \| tar into /usr/local/bin/ | Writes a system binary |

Credentials accessed

Credential	Source	Usage
IMAP email password	Provided by user at install time	IMAP IDLE connection
Telegram INLINECODE11

Read from ~/.openclaw/openclaw.json | Registers /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:

Value	Behaviour
INLINECODE17 (default)	Agent notifies you via Telegram only. Never replies to senders.
INLINECODE18

Agent asks you for explicit approval via Telegram before replying. |
| true | Agent 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`)

CODEBLOCK0

Stage 2: Test Connection (`--test`)

CODEBLOCK1

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

CODEBLOCK2

Stage 4: Verify (automatic)

Other Modes

Register Bot Commands (after update)

CODEBLOCK3

Reconfigure (after update)

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

CODEBLOCK4

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

CODEBLOCK5

Show Config / Uninstall

CODEBLOCK6

Telegram Bot Commands

Click to expand command details

`/beemail_status`

1. systemctl is-active imap-watcher + INLINECODE37
Last 10 log lines: INLINECODE38
UID state: INLINECODE39
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
Optionally run: INLINECODE45

`/beemail`

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

`/beemail_reply`

Show current auto-reply mode:

1. Run INLINECODE48
Report current mode with label: DISABLED / ASK / ENABLED

`/beemail_reply_off`

Disable auto-reply immediately:

1. Run INLINECODE50
Service restarts automatically
Confirm: "🔒 Auto-reply DISABLED"

`/beemail_reply_ask`

Set approval-required mode:

1. Run INLINECODE52
Service restarts automatically
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?"
Only proceed if user confirms
Run INLINECODE54
Service restarts automatically
Confirm: "⚠️ Auto-reply ENABLED"

Telegram Bot Commands Troubleshooting

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

1. Verify registration:

CODEBLOCK7

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: INLINECODE65
Status: INLINECODE66
Restart: INLINECODE67
Config: /opt/imap-watcher/watcher.conf (JSON, chmod 600)
State: INLINECODE69

Architecture

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

邮件推送 — IMAP IDLE → OpenClaw Agent → 用户通知

实时邮件监控：IMAP IDLE检测新邮件，触发OpenClaw代理处理并通过用户活跃渠道通知用户。

安全与权限

代理必须明确告知用户以下所有操作，并在开始安装前获得批准。未经用户确认同意，不得继续。

此技能安装的内容（需要root权限）

操作	路径/目标	说明
系统用户	imap-watcher (useradd -r)	服务以此非root用户身份运行
Python虚拟环境

外部下载（需要用户知晓）

内容	来源	条件
himalaya 二进制文件	github.com/pimalaya/himalaya/releases/latest/	仅当尚未安装时
方法

curl \| tar 到 /usr/local/bin/ | 写入系统二进制文件 |

访问的凭据

凭据	来源	用途
IMAP邮箱密码	安装时由用户提供	IMAP IDLE连接
Telegram botToken

从 ~/.openclaw/openclaw.json 读取 | 通过Telegram API（setMyCommands）注册 /beemail* 命令 |

机器人令牌永远不会被此技能存储。

自动回复行为

默认情况下，代理被指示不回复邮件发件人。这可以防止暴露系统活跃状态，避免钓鱼/垃圾邮件风险。watcher.conf中的allowautoreply字段控制此行为：

值	行为
false（默认）	代理仅通过Telegram通知您。绝不回复发件人。
ask

代理在回复前通过Telegram请求您明确批准。 |
| true | 代理认为适当时可回复发件人（最不安全）。 |

安装时交互式配置。随时通过 --reconfigure + systemctl restart imap-watcher 更改。

如果现有安装中缺少autoreplymode，监控器在启动时会记录[SECURITY] WARNING并通知代理提醒您。在运行--reconfigure之前，将应用安全默认值false。每次操作读取一次，仅用于调用api.telegram.org。代理必须告知用户其机器人令牌将用于修改机器人的命令菜单。

持久性

此技能安装一个持久的后台服务（Restart=always，开机启动）。它维持持续的IMAP连接。服务以专用imap-watcher用户身份运行，而非root用户。

卸载将删除所有内容：服务、systemd单元、/opt/imap-watcher/、日志文件、系统用户以及Telegram机器人命令。

安装流程（4个阶段）

阶段1：依赖项（--deps）

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

阶段2：测试连接（--test）

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

阶段3：安装（仅当阶段1+2通过后）

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

阶段4：验证（自动）

其他模式

注册机器人命令（更新后）

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

重新配置（更新后）

运行clawhub update bee-push-email后，可能会有新的配置字段可用。运行：

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

这将检测现有/opt/imap-watcher/watcher.conf中缺失的字段，并交互式地逐一询问——不会触碰您现有的值。之后重启服务：systemctl restart imap-watcher。

强制重新安装

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

显示配置/卸载

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机器人命令

点击展开命令详情

/beemail_status

1. systemctl is-active imap-watcher + systemctl status imap-watcher --no-pager -l
最后10行日志：journalctl -u imap-watcher -n 10 --no-pager
UID状态：cat /opt/imap-watcher/lastseenuids.json
报告：状态、运行时间、最后邮件、IMAP状态

/beemail_start

1. systemctl start imap-watcher → 等待3秒 → 验证活跃 → 显示最后5行日志

/beemail_stop

1. systemctl stop imap-watcher → 验证不活跃 → 报告

/beemail_test

1. 检查服务活跃 → 从配置读取目标邮箱 → 告知用户发送测试邮件
可选运行：setup.py --test

/beemail

快速摘要：服务活跃？+ 最后处理的邮件 + 一行健康状态

/beemail_reply

显示当前自动回复模式：

1. 运行 python3 /scripts/setup.py --reply-status
报告当前模式并带标签：已禁用 / 询问 / 已启用

/beemailreplyoff

立即禁用自动回复：

1. 运行 python3 /scripts/setup.py --reply-off
服务自动重启
确认：🔒 自动回复已禁用

/beemailreplyask

设置需要批准模式：

1. 运行 python3 /scripts/setup.py --reply-ask
服务自动重启
确认：❓ 自动回复已设为询问

/beemailreplyon

启用自动回复 — 先警告用户：

1. 告知用户：⚠️ 启用自动回复将向所有发件人（包括垃圾邮件/钓鱼邮件）暴露系统活动。确认？
仅在用户确认后继续
运行 python3 /scripts/setup.py --reply-on
服务自动重启
确认：⚠️ 自动回复已启用

Telegram机器人命令故障排除

如果安装后/beemail*命令未出现在Telegram菜单中：

1. 验证注册：