# Gateway

## Gateway คืออะไร?

Gateway คือหัวใจของ Neotask, บริการที่รันระยะยาวตัวเดียวที่จัดการเซสชันเอเจนต์ทั้งหมด ช่องทางการส่งข้อความ การรันเครื่องมือ และการเชื่อมต่ออุปกรณ์ ทุกอย่างไหลผ่าน Gateway

มันคือ WebSocket server ที่รับฟังการเชื่อมต่อจาก client (แอปเดสก์ท็อป แอปมือถือ web dashboard) และจัดการวงจรชีวิตของผู้ช่วย AI ทั้งหมด

## สถาปัตยกรรม

### ส่วนประกอบ

- **WebSocket Server**, รับการเชื่อมต่อ client (พอร์ตเริ่มต้น 18789)
- **HTTP Server**, ให้บริการ Control UI, canvas host และ health endpoint
- **Channel Adapter**, รักษาการเชื่อมต่อกับแพลตฟอร์มการส่งข้อความ (WhatsApp, Telegram, Discord เป็นต้น)
- **Session Manager**, คงและจัดการสถานะการสนทนาของเอเจนต์
- **Cron Scheduler**, รันงานตามกำหนดการและ heartbeat wakeup
- **Plugin Runtime**, โหลดและจัดการวงจรชีวิต plugin
- **Browser Service**, ควบคุม Chromium instance สำหรับการทำงานอัตโนมัติของเว็บ

### โหมด Binding

| โหมด | คำอธิบาย |
|------|-------------|
| **Loopback** | ค่าเริ่มต้น เข้าถึงได้เฉพาะจาก localhost (127.0.0.1) |
| **LAN** | เข้าถึงได้บนเครือข่ายท้องถิ่น ค้นพบได้อัตโนมัติผ่าน Bonjour/mDNS |
| **Tailnet** | เข้าถึงได้ผ่าน Tailscale VPN พร้อม MagicDNS |
| **Custom** | Bind กับที่อยู่เฉพาะ |

### การตรวจสอบสิทธิ์

| วิธีการ | คำอธิบาย |
|--------|-------------|
| **Token** | WebSocket bearer token (UUID หรือ string กำหนดเอง) |
| **Password** | การตรวจสอบสิทธิ์ด้วยรหัสผ่าน (bcrypt hashed) |
| **Trusted Proxy** | สำหรับ reverse proxy ที่มี pre-auth header |
| **Local Trust** | การเชื่อมต่อ loopback ได้รับการอนุมัติอัตโนมัติ |

## การกำหนดค่า

Gateway กำหนดค่าผ่าน `neotask.json` (รูปแบบ JSON5) ส่วนสำคัญ:

| ส่วน | ควบคุม |
|---------|----------|
| `agents` | รายการเอเจนต์ ค่าเริ่มต้น workspace |
| `gateway` | พอร์ต bind mode, auth, พฤติกรรมโหลดซ้ำ |
| `channels` | การกำหนดค่าและข้อมูลประจำตัวต่อช่องทาง |
| `tools` | สิทธิ์เครื่องมือ profile ความปลอดภัย |
| `plugins` | การโหลด plugin การเปิดใช้งาน การกำหนดค่าต่อ plugin |
| `models` | auth ผู้ให้บริการ fallback การตั้งค่าผู้ให้บริการ |
| `skills` | ไดเรกทอรีทักษะ การกำหนดค่าต่อทักษะ |
| `browser` | Browser profile, พอร์ต โหมด headless |
| `cron` | การกำหนดค่า scheduler |
| `session` | กฎการรีเซ็ต เกณฑ์การบีบอัด |
| `messages` | การตั้งค่า TTS นโยบายสื่อ |
| `memory` | การกำหนดค่าการ index หน่วยความจำ |
| `security` | การ sandbox โหมดยกระดับ การอนุมัติ |

### Hot Reload

การเปลี่ยนแปลงการกำหนดค่าสามารถใช้งานได้โดยไม่ต้องรีสตาร์ท:

| โหมด | พฤติกรรม |
|------|----------|
| **Hybrid** (ค่าเริ่มต้น) | ใช้การเปลี่ยนแปลงที่ปลอดภัยแบบ hot-apply รีสตาร์ทสำหรับอื่น ๆ |
| **Hot** | ใช้เฉพาะการเปลี่ยนแปลงที่ปลอดภัยแบบ hot เพิกเฉยต่ออื่น ๆ |
| **Restart** | รีสตาร์ทเมื่อมีการเปลี่ยนแปลงที่ต้องโหลดซ้ำ |
| **Off** | ไม่มีการโหลดซ้ำอัตโนมัติ |

## การเข้าถึงระยะไกล

### Tailscale (แนะนำ)

Tailscale ให้การเข้าถึงระยะไกลที่ปลอดภัยและ zero-config:

- Bind Gateway กับ Tailnet ของคุณ
- เข้าถึงได้จากอุปกรณ์ใด ๆ ในเครือข่าย Tailscale เดียวกัน
- DNS อัตโนมัติผ่าน MagicDNS
- Tailscale Serve สามารถเปิดเผยแดชบอร์ดด้วย HTTPS

### SSH Tunnel

ส่งต่อพอร์ต Gateway ผ่าน SSH:

- ง่าย ปลอดภัย ไม่ต้องเปลี่ยนแปลงการกำหนดค่า
- ทำงานกับเครื่องใด ๆ ที่ใช้ SSH ได้
- รองรับ WebSocket protocol เต็มรูปแบบและ Control UI

### กฎความปลอดภัย

- **Loopback + SSH/Tailscale** คือการรวมกันที่ปลอดภัยที่สุด
- การ binding ที่ไม่ใช่ loopback ต้องการการกำหนดค่า auth token
- การ pin fingerprint TLS มีให้สำหรับความปลอดภัยเพิ่มเติม
- การควบคุมเบราว์เซอร์ถูกปิดใช้งานสำหรับการเชื่อมต่อระยะไกลโดยค่าเริ่มต้น

## การตรวจสอบสุขภาพ

### Health Endpoint

HTTP endpoint `/health` ส่งคืน:

- สถานะ Gateway
- liveness ของ RPC
- สุขภาพต่อช่องทาง (เชื่อมต่อ สถานะ auth จำนวนบัญชี)
- ความพร้อมของเบราว์เซอร์
- เอเจนต์ที่ทำงานอยู่และ node ที่เชื่อมต่อ
- Uptime

### Probe

- **RPC liveness**, WebSocket connect + echo test
- **Channel health**, Auth check + API ping ต่อช่องทาง
- **Browser readiness**, Port check, process check
- **Node connectivity**, Timestamp heartbeat ล่าสุด

## การค้นพบ

### Bonjour/mDNS

เมื่อ bind กับ LAN, Gateway โฆษณาตัวเองผ่าน multicast DNS:

- ประเภทบริการ: `_neotask-gw._tcp`
- รวมถึงพอร์ต transport สถานะ TLS และข้อมูล Tailscale DNS
- แอปคู่หูค้นพบ Gateway โดยอัตโนมัติ

### Wide-Area Discovery

ค้นพบ gateway ข้ามเครือข่ายของคุณพร้อม timeout ที่กำหนดค่าได้ รองรับทั้ง Bonjour ในเครื่องและการค้นพบ DNS ของ Tailscale

## Gateway หลายตัว

คุณสามารถรัน Gateway หลาย instance บนเครื่องเดียวกันโดยใช้ profile:

- แต่ละ profile มี config, workspace, เซสชัน และ state แยกกัน
- พอร์ตที่แตกต่างกันสำหรับแต่ละ Gateway
- มีประโยชน์สำหรับการแยกตัว (ส่วนตัว vs งาน) หรือการทดสอบ

## การวินิจฉัย

### Doctor

เครื่องมือวินิจฉัยในตัวตรวจสอบ:

- ความถูกต้องของการกำหนดค่า
- สิทธิ์ไฟล์
- การเชื่อมต่อช่องทาง
- สถานะ auth ของ model
- ความเข้ากันได้กับเวอร์ชัน Node.js
- การกำหนดค่าที่ผิดปกติทั่วไป

มันสามารถแก้ไขปัญหาหลาย ๆ อย่างโดยอัตโนมัติเมื่อได้รับอนุญาต

### Logging

Gateway log ถูกเขียนลงในไฟล์ JSONL รายวัน:

- การติดตามการใช้โทเค็นต่อการ completion
- Channel event log
- การบันทึกข้อผิดพลาดพร้อม context ที่มีโครงสร้าง
- ระดับ log ที่กำหนดค่าได้