claw-email/README.md

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.