1. つまずきの型
前提未整理、プロセスモデルの誤解（シェル終了で停止）、観測不足（ポート/プロキシ/スリープ）の三類型が多いです。
2. 前提チェック
| 項目 | 指針 | 失敗時 |
|---|---|---|
| Node | ドキュメント推奨に合わせる | ネイティブ拡張不一致 |
| パッケージマネージャ | リポジトリで固定 | ロックファイル漂流 |
| 設定パス | ホーム配下の実ファイルを確認 | 別ファイルを編集 |
| API キー | 最小権限・秘匿管理 | コスト/漏洩 |
3. onboard の意図
鍵、チャネル、実行モード、ワークスペースを一気通貫で書き込む工程です。失敗時はスタックトレースとステップ番号を残してから再試行します。
4. 前景 Gateway とデーモン
初回は stdout/stderr が見える前景が最短。デーモン化は WorkingDirectory と環境変数を明示し、同じヘルスチェックで検証します。
5. 五ステップ検証
リッスン/ヘルス → 最小メッセージ往復 → ログの認証・レート制限ラベル → リバプロなら TLS/WS → バージョンと成功リクエスト ID を記録。
6. ポートとログ
| 症状 | 先に見る | 対処 |
|---|---|---|
| Address already in use | lsof 等 | ゾンビ終了またはポート変更 |
| デーモン即終了 | サービスログ | 前景で再現 |
| チャネル無反応 | Webhook/FW | 内外 curl で切り分け |
| 断続切断 | スリープ・上限 | ホストの電源設計・バックオフ |
lsof -iTCP:PORT -sTCP:LISTEN
運用メモ：
- ログは連続数十行単位で読む。
- マイナー更新の前後でヘルス＋E2E を1回ずつ。
- リモート Mac は空き容量とローテーションを定期確認。
7. リモート Mac 長期運用
スリープ方針、OS 更新後の自動起動、ログローテ、サービスユーザの一貫性を Runbook 化します。
8. 再現可能な起動経路
機能リストより、onboard 出力とユニットファイルとヘルスコマンドを版管理する方が TCO を下げます。GPU 作業と同居させないためにゲートウェイを専用リモート Mac に置く構成も有効です。
ローカルで不安定なら、MACGPU のリモート Mac で常時電源とディスク余裕を確保し、時間課金で試験から始められます。