Email-OpenClaw Bridge
Tự động xử lý email bằng OpenClaw AI theo luồng:
Ingress (IMAP) → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
Tính năng
- IMAP IDLE — theo dõi mailbox realtime, nhận email mới tức thì
- Threading — giữ nguyên email thread qua
In-Reply-To/References - Idempotency — chống duplicate theo
message_id - Anti-loop & Whitelist — bỏ qua email từ chính hệ thống, chỉ xử lý sender được phép
- Retry — tối đa 3 lần với backoff 1s → 5s → 15s cho cả OpenClaw và SMTP
- Stateful — SQLite lưu trạng thái pipeline, không mất dữ liệu khi restart
Kiến trúc
cmd/bridge/main.go Entrypoint
internal/
├── config/ Đọc cấu hình từ .env
├── database/ SQLite + GORM, auto-migrate
├── logging/ Structured JSON logging (slog)
├── api/ HTTP server (Gin): health checks, webhook callback
├── mail/ IMAP ingress + SMTP egress
└── ai_client/ OpenClaw HTTP dispatch
Yêu cầu
- Go 1.23+
- Docker & Docker Compose (cho deploy)
Quickstart
1. Cấu hình
cp .env.example .env
# Sửa .env với thông tin IMAP/SMTP/OpenClaw thực tế
2. Chạy local (development)
go run ./cmd/bridge
3. Chạy bằng Docker
docker compose up -d
docker logs -f claw-email-bridge
Cấu hình (.env)
| Biến | Bắt buộc | Mô tả |
|---|---|---|
IMAP_HOST |
✅ | IMAP server hostname |
IMAP_PORT |
✅ | IMAP port (thường 993) |
IMAP_USER |
✅ | IMAP username |
IMAP_PASS |
✅ | IMAP password |
SMTP_HOST |
✅ | SMTP server hostname |
SMTP_PORT |
✅ | SMTP port (thường 587) |
SMTP_USER |
✅ | SMTP username |
SMTP_PASS |
✅ | SMTP password |
OPENCLAW_URL |
✅ | OpenClaw API endpoint |
OPENCLAW_API_KEY |
OpenClaw API key (nếu cần) | |
BRIDGE_CALLBACK_TOKEN |
✅ | Token xác thực webhook callback |
SYSTEM_EMAIL |
✅ | Email của hệ thống (dùng cho anti-loop) |
WHITELIST_EMAILS |
Danh sách email được phép, phân cách bằng dấu phẩy | |
IMAP_PROXY_URL |
SOCKS5 proxy cho IMAP (vd: socks5://user:pass@host:port) |
|
LISTEN_ADDR |
Địa chỉ bind HTTP server cục bộ (mặc định :8080) |
|
CALLBACK_BASE_URL |
Base URL public để tạo callback_url gửi OpenClaw (mặc định theo LISTEN_ADDR, ví dụ http://localhost:8080) |
Health Checks
| Endpoint | Mục đích |
|---|---|
GET /healthz |
Liveness — process còn sống |
GET /readyz |
Readiness — DB writable + config hợp lệ |
Pipeline trạng thái
RECEIVED → AI_PROCESSING → CALLBACK_DONE → COMPLETED
↓ ↓ ↓
IGNORED FAILED SMTP_RETRYING → FAILED
Công nghệ
| Thành phần | Thư viện |
|---|---|
| HTTP Server | gin-gonic/gin |
| Database | GORM + modernc.org/sqlite (pure Go, no CGO) |
| IMAP | emersion/go-imap |
| Logging | log/slog (stdlib) |
| Config | joho/godotenv |
License
Private — internal use only.