安全扫描（ClawHub）

• VirusTotal ：可疑
• OpenClaw ：可疑

OpenClaw 评估

The skill's code and instructions match the claimed purpose (an IMAP IDLE watcher that runs user commands), but there are several mismatches and operational risks you should understand before installing (missing metadata declarations, systemd/root installation, plaintext credential handling, and running arbitrary shell commands).

安装（复制给龙虾 AI）

将下方整段复制到龙虾中文库对话中，由龙虾按 SKILL.md 完成安装。

请把本段交给龙虾中文库（龙虾 AI）执行：为本机安装 OpenClaw 技能「IMAP IDLE Watcher」。简介：Real-time email monitoring using IMAP IDLE — no OAuth, no token expiration. Set…。
请 fetch 以下地址读取 SKILL.md 并按文档完成安装：https://raw.githubusercontent.com/openclaw/skills/refs/heads/main/skills/axellageraldinc/imap-idle-watcher/SKILL.md
（来源：yingzhi8.cn 技能库）

SKILL.md

打开原始 SKILL.md（GitHub raw）

---
name: imap-idle-watcher
description: >
  Real-time email monitoring using IMAP IDLE — no OAuth, no token expiration.
  Sets up a persistent connection to any IMAP server (Gmail, Outlook, Yahoo, etc.)
  and triggers a user-defined command instantly when new email arrives.
  Runs as a systemd service with auto-reconnect.
  Use when: (1) setting up email-triggered automation, (2) watching an inbox for
  new messages in real-time, (3) replacing OAuth-based email polling that keeps
  breaking due to token expiry, (4) building email-to-webhook or email-to-script
  pipelines. NOT for: sending email, reading/parsing email bodies, or
  non-Linux systems without systemd.
---

# IMAP IDLE Watcher

Real-time email watcher. Uses IMAP IDLE (server push) instead of polling.
App passwords instead of OAuth — no token expiry, no re-auth.

## Quick Start

### Interactive
```bash
bash scripts/setup_service.sh
```
Prompts for email, detects provider, gives app password link, tests connection, installs service.

### Non-interactive
```bash
bash scripts/setup_service.sh 
  --account "user@gmail.com" 
  --password "xxxx xxxx xxxx xxxx" 
  --command "python3 /path/to/handler.py" 
  --service-name my-watcher
```

### Test connection only
```bash
bash scripts/setup_service.sh --test --account "user@gmail.com" --password "xxxx"
```

## Configuration (env vars)

| Variable | Default | Description |
|----------|---------|-------------|
| `IMAP_ACCOUNT` | (required) | Email address |
| `IMAP_PASSWORD` | (required) | App password |
| `IMAP_HOST` | `imap.gmail.com` | IMAP server (auto-detected from email) |
| `IMAP_PORT` | `993` | IMAP port |
| `IMAP_FOLDER` | `INBOX` | Folder to watch |
| `ON_NEW_MAIL_CMD` | (optional) | Shell command to run on new mail |
| `FILTER_FROM` | (optional) | Only trigger for these senders (comma-separated, substring match) |
| `FILTER_SUBJECT` | (optional) | Only trigger for these subjects (comma-separated, substring match) |
| `IDLE_TIMEOUT` | `1200` | Seconds before IDLE renewal (max 1740) |
| `DEBOUNCE_SECONDS` | `10` | Min seconds between command runs |

## Filtering

Only process emails matching specific senders or subjects:

```bash
FILTER_FROM=paypal.com,stripe.com      # from contains either (OR)
FILTER_SUBJECT=payment,invoice         # subject contains either (OR)
```

- Case-insensitive substring match
- Both FROM and SUBJECT must match if both set (AND)
- Within each filter, any value matches (OR)
- No filter set = process all emails

## Writing a Handler

The agent should write a handler script based on the user's intent. The daemon passes email metadata as env vars:

| Variable | Example |
|----------|---------|
| `MAIL_FROM` | `John Doe <john@example.com>` |
| `MAIL_SUBJECT` | `Your order has shipped` |
| `MAIL_DATE` | `Mon, 17 Mar 2026 10:30:00 +0700` |
| `MAIL_UID` | `12345` |

### Workflow

1. User describes what they want (e.g. "watch my inbox, summarize new emails")
2. Agent writes a handler script (Python/Bash) that reads the env vars and does what the user asked
3. Agent saves it somewhere persistent (e.g. `~/email-handler.py`)
4. Agent runs `setup_service.sh` with `--command "python3 ~/email-handler.py"`

### Example: user says "notify me about new emails"

Agent writes `~/email-handler.py`:
```python
#!/usr/bin/env python3
import os
print(f"New mail from {os.environ.get('MAIL_FROM', '?')}: {os.environ.get('MAIL_SUBJECT', '?')}")
```

Then wires it up:
```bash
bash scripts/setup_service.sh --account "user@gmail.com" --password "xxxx" 
  --command "python3 ~/email-handler.py"
```

The handler is the agent's job — adapt it to whatever the user needs.

## How It Works

1. Connects to IMAP server with app password (SSL)
2. Enters IDLE mode — server holds connection open
3. Server pushes notification when new mail arrives (instant, no polling)
4. Daemon runs `ON_NEW_MAIL_CMD` with email metadata as env vars (`MAIL_FROM`, `MAIL_SUBJECT`, `MAIL_DATE`, `MAIL_UID`)
5. Returns to IDLE. Renews every 20 min per RFC 2177.
6. Auto-reconnects on disconnect (backoff: 5s → 10s → 30s → 60s → 120s)

## Service Management

```bash
systemctl status <service-name>
journalctl -u <service-name> -f
systemctl restart <service-name>
systemctl stop <service-name>
```

## Uninstall

```bash
bash scripts/setup_service.sh --uninstall --service-name <service-name>
```

## Provider Setup Guides

- Gmail: see [references/gmail.md](references/gmail.md)
- Outlook: see [references/outlook.md](references/outlook.md)
- Yahoo: see [references/yahoo.md](references/yahoo.md)

## Troubleshooting

See [references/troubleshooting.md](references/troubleshooting.md) for common errors and fixes.