claw-email/README.md

Email-OpenClaw Bridge

Bridge tự động xử lý email bằng OpenClaw AI theo luồng:

Ingress (IMAP) → Safety Checks → External Rules → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)

README này tập trung vào onboarding và vận hành cơ bản. Chi tiết kỹ thuật hiện hành được tách sang docs/architecture/overview.md.

Tính năng chính

• Theo dõi mailbox realtime bằng IMAP IDLE
• Giữ thread email qua In-Reply-To và References
• Chống duplicate theo message_id
• Chặn anti-loop và hỗ trợ whitelist/blocklist
• Gửi callback vào bridge rồi phản hồi lại qua SMTP
• Lưu trạng thái pipeline bằng SQLite để không mất tiến trình khi restart

Yêu cầu tối thiểu

• Go 1.23+
• Docker và Docker Compose nếu chạy bằng container

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

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 là 993
IMAP_USER	✅	IMAP username
IMAP_PASS	✅	IMAP password
SMTP_HOST	✅	SMTP server hostname
SMTP_PORT	✅	SMTP port, thường là 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 bridge, dùng cho anti-loop
WHITELIST_EMAILS		Danh sách email được phép, phân cách bằng dấu phẩy
BLOCKLIST_EMAILS		Danh sách email bị chặn, phân cách bằng dấu phẩy
IMAP_PROXY_URL		Proxy cho IMAP, hỗ trợ socks5://, http://, https://
LISTEN_ADDR		Địa chỉ bind HTTP server, mặc định :8080
CALLBACK_BASE_URL		Base URL public để tạo callback_url, mặc định suy ra từ LISTEN_ADDR

Health checks

Endpoint	Mục đích
GET /healthz	Liveness check, xác nhận process còn sống
GET /readyz	Readiness check, xác nhận DB writable và config bắt buộc hợp lệ

Đọc thêm

• Technical overview
• Architecture Decision Records

License

Private — internal use only.