Email Webhook Receiver
This skill provides a secure endpoint to receive emails as standardized JSON webhooks and automatically wakes the agent.
🤖 Agent Setup (Post-Install)
After installing and starting this skill, add the following logic to your HEARTBEAT.md:
CODEBLOCK0
💡 You don't need to know the user's channel in advance — use the most recently active channel from your session history. If you're unsure how to reach the user, ask them directly.
The skill fires openclaw system event on each incoming email to wake you immediately. Your HEARTBEAT.md logic will then run and handle the notification.
⚡️ Wake Mechanism
When an email is received, the server invokes openclaw system event --mode now. This ensures the agent is notified immediately and can process the incoming communication without waiting for the next heartbeat cycle.
🚨 Security & Privacy
Command Injection Protection
The server uses secure process spawning (
child_process.spawn) with argument arrays instead of shell execution. User-controlled input (email headers) cannot be used to execute arbitrary system commands.
Path Traversal Protection
The
INBOX_FILE parameter is sanitized using
path.basename(), ensuring that files are only written within the server's working directory.
Authentication
A strong
WEBHOOK_SECRET environment variable is
REQUIRED for the server to start. All incoming requests must provide this secret in the
Authorization: Bearer <secret> header.
Data Storage
- - Local Inbox: Incoming emails (raw body and metadata) are appended to a local
inbox.jsonl file. - Cleanup: Users should periodically rotate or delete the inbox file to save disk space and protect privacy.
Environment Variables
| Variable | Required | Default | Description |
|---|
| INLINECODE9 | Yes | — | Secret token for webhook authentication. |
| INLINECODE10 |
Yes | — | Your agent ID (e.g.
skippy). Without this, incoming emails wake
ALL agents on the server. |
|
PORT | No |
2083 | Port to listen on. Configurable — set to match your
OPENCLAW_WEBHOOK_URL. |
|
INBOX_FILE | No |
inbox.jsonl | Filename for the activity feed. |
Setup
- 1. Install dependencies:
npm install express@4.21.2
- 2. Start Server:
CODEBLOCK2
Cloudflare Setup
This server listens on port 2082. Cloudflare natively supports port 2082 as an HTTP origin port with Flexible SSL.
When configuring your Cloudflare Email Worker, set OPENCLAW_WEBHOOK_URL using http:// with the port explicitly:
CODEBLOCK3
Port 2083 is a Cloudflare-supported port. Works with Flexible SSL — the server uses a self-signed certificate (auto-generated on first run) which Cloudflare accepts on this port.
⚠️ If you use a different port, set the PORT env var when starting the server.
⚠️ If you omit the port in the Worker URL, Cloudflare defaults to port 80 → 404.
DNS setup: create an A record for webhook.yourdomain.com pointing to your server IP with the orange cloud (proxy) enabled.
Runtime Requirements
Requires:
express,
node,
openclaw CLI.
邮件Webhook接收器
该技能提供一个安全端点，用于接收标准化JSON webhook格式的邮件，并自动唤醒智能体。
🤖 智能体设置（安装后）
安装并启动此技能后，将以下逻辑添加到您的HEARTBEAT.md文件中：
markdown
📧 入站邮件检查
- - 读取（通过INBOX_FILE配置，默认：当前工作目录下的inbox.jsonl）
- 将最新的receivedAt时间戳与您上次检查的时间戳进行比较
- 如果自上次检查后有新邮件：
- 通过用户最后活跃的通信渠道（Discord、WhatsApp等）通知用户
- 格式：📧 来自[发件人]的新邮件：[主题] — [文本预览]
- 更新您上次检查的时间戳
💡 您无需事先了解用户的通信渠道——使用会话历史中最近活跃的渠道。如果不确定如何联系用户，请直接询问。
该技能在每封入站邮件到达时触发openclaw system event，立即唤醒您。您的HEARTBEAT.md逻辑随后将运行并处理通知。
⚡️ 唤醒机制
当收到邮件时，服务器调用openclaw system event --mode now。这确保智能体立即收到通知，无需等待下一个心跳周期即可处理传入的通信。
🚨 安全与隐私
命令注入防护
服务器使用安全的进程生成方式（child_process.spawn），采用参数数组而非shell执行。用户控制的输入（邮件头）无法用于执行任意系统命令。
路径遍历防护
INBOX_FILE参数通过path.basename()进行清理，确保文件仅写入服务器的工作目录内。
身份验证
服务器启动
必须设置强WEBHOOK_SECRET环境变量。所有传入请求必须在Authorization: Bearer
头中提供此密钥。
数据存储
- - 本地收件箱：入站邮件（原始正文和元数据）追加到本地inbox.jsonl文件中。
- 清理：用户应定期轮换或删除收件箱文件以节省磁盘空间并保护隐私。
环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|
| WEBHOOKSECRET | 是 | — | Webhook身份验证的密钥令牌。 |
| OPENCLAWAGENT_ID |
是 | — | 您的智能体ID（例如skippy）。未设置时，入站邮件将唤醒服务器上的所有智能体。 |
| PORT | 否 | 2083 | 监听端口。可配置——设置为与您的OPENCLAWWEBHOOKURL匹配。 |
| INBOX_FILE | 否 | inbox.jsonl | 活动源的文件名。 |
设置
- 1. 安装依赖：
bash
npm install express@4.21.2
- 2. 启动服务器：
bash
WEBHOOKSECRET=your-strong-token node scripts/webhookserver.js
Cloudflare设置
此服务器监听端口2082。Cloudflare原生支持端口2082作为HTTP源端口，使用Flexible SSL。
配置Cloudflare邮件Worker时，使用http://并显式指定端口设置OPENCLAWWEBHOOKURL：
https://webhook.yourdomain.com:2083/api/email
端口2083是Cloudflare支持的端口。适用于Flexible SSL——服务器使用自签名证书（首次运行时自动生成），Cloudflare在此端口上接受该证书。
⚠️ 如果使用其他端口，请在启动服务器时设置PORT环境变量。
⚠️ 如果在Worker URL中省略端口，Cloudflare默认使用端口80 → 404。
DNS设置：为webhook.yourdomain.com创建A记录，指向您的服务器IP，并启用橙色云（代理）。
运行时要求
需要：express、node、openclaw CLI。
