thuanleandClaude Opus 4.7
92121278bb
- ADR-0002: external rules pipeline architecture - README: updated flow to show safety checks → rules → dispatch - .env.example: added BLOCKLIST_EMAILS Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# Email-OpenClaw Bridge
|
|
|
|
Tự động xử lý email bằng OpenClaw AI theo luồng:
|
|
|
|
```
|
|
Ingress (IMAP) → Safety Checks → External Rules → Apply Context → 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
|
|
- **External Rules** — pipeline configurable: whitelist, blocklist, và rule metadata cho dispatch
|
|
- **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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Sửa .env với thông tin IMAP/SMTP/OpenClaw thực tế
|
|
```
|
|
|
|
### 2. Chạy local (development)
|
|
|
|
```bash
|
|
go run ./cmd/bridge
|
|
```
|
|
|
|
### 3. Chạy bằng Docker
|
|
|
|
```bash
|
|
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](https://github.com/gin-gonic/gin) |
|
|
| Database | [GORM](https://gorm.io) + [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) (pure Go, no CGO) |
|
|
| IMAP | [emersion/go-imap](https://github.com/emersion/go-imap) |
|
|
| Logging | [log/slog](https://pkg.go.dev/log/slog) (stdlib) |
|
|
| Config | [joho/godotenv](https://github.com/joho/godotenv) |
|
|
|
|
## License
|
|
|
|
Private — internal use only.
|