84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
# Email-OpenClaw Bridge
|
|
|
|
Bridge tự động xử lý email bằng OpenClaw AI theo luồng:
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Sửa .env với thông tin IMAP/SMTP/OpenClaw thực tế
|
|
```
|
|
|
|
### 2. Chạy local
|
|
|
|
```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 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](docs/architecture/overview.md)
|
|
- [Architecture Decision Records](docs/adr/README.md)
|
|
|
|
## License
|
|
|
|
Private — internal use only.
|