# 게이트웨이

## 게이트웨이란 무엇인가?

게이트웨이는 Neotask의 핵심입니다, 모든 에이전트 세션, 메시지 채널, 도구 실행, 기기 연결을 관리하는 단일 장기 실행 서비스. 모든 것이 게이트웨이를 통해 흐릅니다.

클라이언트(데스크톱 앱, 모바일 앱, 웹 대시보드)의 연결을 받고 전체 AI 어시스턴트 수명 주기를 관리하는 WebSocket 서버입니다.

## 아키텍처

### 구성 요소

- **WebSocket 서버**, 클라이언트 연결을 받습니다 (기본 포트 18789)
- **HTTP 서버**, 제어 UI, 캔버스 호스트, 상태 엔드포인트를 제공합니다
- **채널 어댑터**, 메시지 플랫폼(WhatsApp, Telegram, Discord 등)에 대한 연결을 유지합니다
- **세션 관리자**, 에이전트 대화 상태를 지속하고 관리합니다
- **크론 스케줄러**, 예약된 작업과 하트비트 깨우기를 실행합니다
- **플러그인 런타임**, 플러그인 수명 주기를 로드하고 관리합니다
- **브라우저 서비스**, 웹 자동화를 위한 Chromium 인스턴스를 제어합니다

### 바인딩 모드

| 모드 | 설명 |
|------|-------------|
| **루프백** | 기본값. localhost(127.0.0.1)에서만 접근 가능 |
| **LAN** | 로컬 네트워크에서 접근 가능. Bonjour/mDNS를 통해 자동 발견 가능 |
| **Tailnet** | MagicDNS로 Tailscale VPN을 통해 접근 가능 |
| **커스텀** | 특정 주소에 바인딩 |

### 인증

| 방법 | 설명 |
|--------|-------------|
| **토큰** | WebSocket 베어러 토큰 (UUID 또는 커스텀 문자열) |
| **비밀번호** | 비밀번호 기반 인증 (bcrypt 해시) |
| **신뢰할 수 있는 프록시** | 사전 인증 헤더가 있는 리버스 프록시용 |
| **로컬 신뢰** | 루프백 연결 자동 승인 |

## 구성

게이트웨이는 `neotask.json`(JSON5 형식)을 통해 구성됩니다. 주요 섹션:

| 섹션 | 제어 내용 |
|---------|----------|
| `agents` | 에이전트 목록, 기본값, 워크스페이스 |
| `gateway` | 포트, 바인딩 모드, 인증, 재로드 동작 |
| `channels` | 채널별 구성 및 자격 증명 |
| `tools` | 도구 권한, 프로필, 보안 |
| `plugins` | 플러그인 로드, 활성화, 플러그인별 구성 |
| `models` | 제공업체 인증, 폴백, 제공업체 설정 |
| `skills` | 스킬 디렉토리, 스킬별 구성 |
| `browser` | 브라우저 프로필, 포트, 헤드리스 모드 |
| `cron` | 스케줄러 구성 |
| `session` | 재설정 규칙, 압축 임계값 |
| `messages` | TTS 설정, 미디어 정책 |
| `memory` | 메모리 인덱싱 구성 |
| `security` | 샌드박싱, 상승 모드, 승인 |

### 핫 리로드

재시작 없이 구성 변경을 적용할 수 있습니다:

| 모드 | 동작 |
|------|----------|
| **하이브리드** (기본값) | 안전한 변경을 핫 적용하고 다른 변경은 재시작합니다 |
| **핫** | 핫 안전 변경만 적용하고 다른 것은 무시합니다 |
| **재시작** | 재로드가 필요한 변경 시 재시작합니다 |
| **끄기** | 자동 재로드 없음 |

## 원격 접근

### Tailscale (권장)

Tailscale은 안전한 제로 구성 원격 접근을 제공합니다:

- 게이트웨이를 Tailnet에 바인딩합니다
- 동일한 Tailscale 네트워크의 모든 기기에서 접근합니다
- MagicDNS를 통한 자동 DNS
- Tailscale Serve는 HTTPS로 대시보드를 노출할 수 있습니다

### SSH 터널

SSH를 통해 게이트웨이 포트를 포워딩합니다:

- 간단하고 안전하며 구성 변경이 필요하지 않습니다
- SSH 가능한 모든 머신과 작동합니다
- 전체 WebSocket 프로토콜과 제어 UI를 지원합니다

### 보안 규칙

- **루프백 + SSH/Tailscale**이 가장 안전한 조합입니다
- 비루프백 바인딩에는 인증 토큰 구성이 필요합니다
- 추가 보안을 위한 TLS 지문 고정이 가능합니다
- 브라우저 제어는 기본적으로 원격 연결에서 비활성화됩니다

## 상태 모니터링

### 상태 엔드포인트

`/health` HTTP 엔드포인트는 다음을 반환합니다:

- 게이트웨이 상태
- RPC 라이브니스
- 채널별 상태 (연결됨, 인증 상태, 계정 수)
- 브라우저 준비 상태
- 활성 에이전트 및 연결된 노드
- 가동 시간

### 프로브

- **RPC 라이브니스**, WebSocket 연결 + 에코 테스트
- **채널 상태**, 채널별 인증 확인 + API 핑
- **브라우저 준비 상태**, 포트 확인, 프로세스 확인
- **노드 연결성**, 마지막 하트비트 타임스탬프

## 발견

### Bonjour/mDNS

LAN에 바인딩되면 게이트웨이는 멀티캐스트 DNS를 통해 자신을 알립니다:

- 서비스 유형: `_neotask-gw._tcp`
- 포트, 전송, TLS 상태, Tailscale DNS 정보 포함
- 동반 앱이 게이트웨이를 자동으로 발견합니다

### 광역 발견

구성 가능한 타임아웃으로 네트워크 전체의 게이트웨이를 발견합니다. 로컬 Bonjour와 Tailscale DNS 발견을 모두 지원합니다.

## 여러 게이트웨이

프로필을 사용하여 동일한 머신에서 여러 게이트웨이 인스턴스를 실행할 수 있습니다:

- 각 프로필에는 별도의 구성, 워크스페이스, 세션, 상태가 있습니다
- 각 게이트웨이에 다른 포트
- 격리(개인 vs 업무) 또는 테스트에 유용합니다

## 진단

### 닥터

내장 진단 도구는 다음을 확인합니다:

- 구성 유효성
- 파일 권한
- 채널 연결성
- 모델 인증 상태
- Node.js 버전 호환성
- 일반적인 잘못된 구성

권한이 주어지면 많은 문제를 자동으로 수정할 수 있습니다.

### 로깅

게이트웨이 로그는 일별 JSONL 파일에 기록됩니다:

- 완성별 토큰 사용량 추적
- 채널 이벤트 로그
- 구조화된 컨텍스트가 있는 오류 로깅
- 구성 가능한 로그 수준