# Gateway

## Gatewayとは何ですか？

GatewayはNeotaskの中核, , すべてのエージェントセッション、メッセージングチャンネル、ツール実行、デバイス接続を管理する単一の長期実行サービスです。すべてのものがGatewayを通じて流れます。

クライアント（デスクトップアプリ、モバイルアプリ、Webダッシュボード）からの接続を受け入れ、AIアシスタントのライフサイクル全体を管理するWebSocketサーバーです。

## アーキテクチャ

### コンポーネント

- **WebSocketサーバー**, クライアント接続を受け入れます（デフォルトポート18789）
- **HTTPサーバー**, コントロールUI、キャンバスホスト、ヘルスエンドポイントを提供
- **チャンネルアダプター**, メッセージングプラットフォーム（WhatsApp、Telegram、Discordなど）への接続を維持
- **セッションマネージャー**, エージェントの会話状態を永続化・管理
- **CronスケジューラZ**, スケジュールされたジョブとハートビートウェイクアップを実行
- **プラグインランタイム**, プラグインのライフサイクルを読み込み・管理
- **ブラウザサービス**, Web自動化のためのChromiumインスタンスを制御

### バインディングモード

| モード | 説明 |
|------|-------------|
| **ループバック** | デフォルト。localhost（127.0.0.1）からのみアクセス可能 |
| **LAN** | ローカルネットワーク上でアクセス可能。Bonjour/mDNSで自動ディスカバリー |
| **Tailnet** | MagicDNS付きTailscale VPN経由でアクセス可能 |
| **カスタム** | 特定のアドレスにバインド |

### 認証

| 方法 | 説明 |
|--------|-------------|
| **トークン** | WebSocketベアラートークン（UUIDまたはカスタム文字列） |
| **パスワード** | パスワードベースの認証（bcryptハッシュ） |
| **信頼されたプロキシ** | 事前認証ヘッダーを持つリバースプロキシ向け |
| **ローカルトラスト** | ループバック接続は自動承認 |

## 設定

GatewayはJSON5形式の`neotask.json`で設定します。主要なセクション：

| セクション | 制御内容 |
|---------|----------|
| `agents` | エージェントリスト、デフォルト、ワークスペース |
| `gateway` | ポート、バインドモード、認証、リロード動作 |
| `channels` | チャンネルごとの設定と認証情報 |
| `tools` | ツールの権限、プロファイル、セキュリティ |
| `plugins` | プラグインの読み込み、有効化、プラグインごとの設定 |
| `models` | プロバイダー認証、フォールバック、プロバイダー設定 |
| `skills` | スキルディレクトリ、スキルごとの設定 |
| `browser` | ブラウザプロファイル、ポート、ヘッドレスモード |
| `cron` | スケジューラー設定 |
| `session` | リセットルール、コンパクションしきい値 |
| `messages` | TTS設定、メディアポリシー |
| `memory` | メモリインデックス設定 |
| `security` | サンドボックス化、エレベーテッドモード、承認 |

### ホットリロード

設定変更は再起動なしで適用できます：

| モード | 動作 |
|------|----------|
| **ハイブリッド**（デフォルト） | 安全な変更はホット適用、その他は再起動 |
| **ホット** | ホット安全な変更のみ適用、その他は無視 |
| **再起動** | リロードが必要な変更があれば再起動 |
| **オフ** | 自動リロードなし |

## リモートアクセス

### Tailscale（推奨）

Tailscaleは安全なゼロ設定のリモートアクセスを提供します：

- GatewayをTailnetにバインド
- 同じTailscaleネットワーク上のどのデバイスからもアクセス可能
- MagicDNSによる自動DNS
- Tailscale ServeはダッシュボードをHTTPSで公開可能

### SSHトンネル

SSHでGatewayポートを転送：

- シンプルで安全、設定変更不要
- SSH対応のどのマシンでも動作
- 完全なWebSocketプロトコルとコントロールUIをサポート

### セキュリティルール

- **ループバック + SSH/Tailscale**が最も安全な組み合わせ
- ループバック以外のバインドには認証トークンの設定が必要
- 追加のセキュリティのためのTLSフィンガープリントピン留めが利用可能
- ブラウザ制御はデフォルトでリモート接続には無効

## ヘルスモニタリング

### ヘルスエンドポイント

`/health` HTTPエンドポイントが返すもの：

- Gatewayの状態
- RPCの生存確認
- チャンネルごとのヘルス（接続状態、認証状態、アカウント数）
- ブラウザの準備状態
- アクティブなエージェントと接続済みノード
- アップタイム

### プローブ

- **RPC生存確認**, WebSocket接続 + エコーテスト
- **チャンネルヘルス**, 認証チェック + チャンネルごとのAPIping
- **ブラウザ準備状態**, ポートチェック、プロセスチェック
- **ノード接続性**, 最後のハートビートタイムスタンプ

## ディスカバリー

### Bonjour/mDNS

LANにバインドされると、GatewayはマルチキャストDNSで自身を通知します：

- サービスタイプ：`_neotask-gw._tcp`
- ポート、トランスポート、TLS状態、Tailscale DNS情報を含む
- コンパニオンアプリがGatewayを自動的に検出

### ワイドエリアディスカバリー

設定可能なタイムアウトでネットワーク全体のGatewayを検出します。ローカルBonjourとTailscale DNSディスカバリーの両方をサポート。

## 複数のGateway

同じマシンでプロファイルを使用して複数のGatewayインスタンスを実行できます：

- 各プロファイルは別々の設定、ワークスペース、セッション、状態を持ちます
- Gatewayごとに異なるポート
- 分離（個人 vs 仕事）やテストに便利

## 診断

### Doctor

組み込みの診断ツールが確認するもの：

- 設定の有効性
- ファイルの権限
- チャンネル接続性
- モデルの認証状態
- Node.jsバージョンの互換性
- よくある設定ミス

許可を与えると多くの問題を自動的に修正できます。

### ロギング

Gatewayのログは日次JSONLファイルに書き込まれます：

- 完了ごとのトークン使用量の追跡
- チャンネルイベントログ
- 構造化されたコンテキスト付きのエラーロギング
- 設定可能なログレベル