起動する Gateway：デーモンプロセスと実行モード

学習後の目標

コマンドラインから Gateway フォアグラウンドプロセスを起動する
Gateway をバックグラウンドデーモンプロセスとして設定する（macOS LaunchAgent / Linux systemd / Windows Scheduled Task）
異なるバインディングモード（loopback / LAN / Tailnet）と認証方式を理解する
開発モードと本番モードを切り替える
--force を使用して使用中のポートを強制的に解放する

現在の課題

ウィザード設定が完了し、Gateway の基本設定は整っています。しかし：

Gateway を使用するたびに手動で端末でコマンドを実行する必要がありますか？
端末ウィンドウを閉じると Gateway が停止し、AI アシスタントも「オフライン」になりますか？
LAN や Tailscale ネットワークで Gateway にアクセスしたい場合、設定方法がわからない？
Gateway の起動に失敗したが、設定問題なのかポートが使用中なのか不明？

いつ使用するか

推奨される起動方法：

シナリオ	使用コマンド	説明
日常使用	`clawdbot gateway install` + `clawdbot gateway start`	バックグラウンドサービスとして自動起動
開発デバッグ	`clawdbot gateway --dev`	開発設定を作成し、自動再ロード
一時テスト	`clawdbot gateway`	フォアグラウンド実行、ログを端末に直接出力
ポート競合	`clawdbot gateway --force`	ポートを強制的に解放して起動
LAN アクセス	`clawdbot gateway --bind lan`	LAN デバイスからの接続を許可
Tailscale リモートアクセス	`clawdbot gateway --tailscale serve`	Tailscale ネットワーク経由で Gateway を公開

🎒 開始前の準備

事前チェック

Gateway を起動する前に、以下を確認してください：

✅ ウィザード設定（clawdbot onboard）が完了しているか、または手動で gateway.mode=local が設定されている
✅ AI モデルが設定されている（Anthropic / OpenAI / OpenRouter など）
✅ 外部ネットワーク（LAN / Tailnet）にアクセスする場合、認証方式が設定されている
✅ 使用シナリオを理解している（ローカル開発 vs 本番稼働）

コアコンセプト

Gateway とは何か？

Gateway は Clawdbot の WebSocket コントロールプレーンであり、次の責任を持ちます：

セッション管理：すべての AI 対話セッションの状態を維持
チャンネル接続：WhatsApp、Telegram、Slack など 12 以上のメッセージチャンネルに接続
ツール呼び出し：ブラウザ自動化、ファイル操作、スケジュールタスクなどのツール実行を調整
ノード管理：macOS / iOS / Android デバイスノードを管理
イベント配信：AI の思考の進捗、ツール呼び出しの結果などのリアルタイムイベントをプッシュ

なぜデーモンプロセスが必要か？

バックグラウンドサービスとして実行される Gateway には次の利点があります：

常時接続：端末を閉じても、AI アシスタントは引き続き使用可能
自動起動：システム再起動後にサービスを自動的に復元（macOS LaunchAgent / Linux systemd）
統一管理：start / stop / restart コマンドでライフサイクルを制御
ログ集中：システムレベルのログ収集により、トラブルシューティングが容易

手順を追って

ステップ 1：Gateway を起動する（フォアグラウンドモード）

理由

フォアグラウンドモードは開発テストに適しており、ログが端末に直接出力されるため、Gateway の状態をリアルタイムで確認できます。

bash

# デフォルト設定で起動（127.0.0.1:18789 をリスン）
clawdbot gateway

# ポートを指定して起動
clawdbot gateway --port 19001

# 詳細ログを有効化
clawdbot gateway --verbose

表示される内容：

bash

✓ agent model: anthropic/claude-opus-4-5
✓ listening on ws://127.0.0.1:18789 (PID 12345)
✓ log file: /Users/you/.clawdbot/logs/gateway.log

チェックポイント

listening on ws://... が表示されたら起動成功です
表示された PID（プロセス ID）を記録しておくと、後続のデバッグに役立ちます
デフォルトポートは 18789 ですが、--port で変更可能です

ステップ 2：バインディングモードを設定する

理由

デフォルトでは Gateway はローカルループバックアドレス（127.0.0.1）のみをリスンするため、同じマシンからのみ接続できます。LAN や Tailscale ネットワークからアクセスする場合、バインディングモードを調整する必要があります。

bash

# ローカルループバックのみ（デフォルト、最も安全）
clawdbot gateway --bind loopback

# LAN アクセス（認証が必要）
clawdbot gateway --bind lan --token "your-token"

# Tailscale ネットワークアクセス
clawdbot gateway --bind tailnet --token "your-token"

# 自動検出（ローカル + LAN）
clawdbot gateway --bind auto

表示される内容：

bash

# loopback モード
✓ listening on ws://127.0.0.1:18789 (PID 12345)

# lan モード
✓ listening on ws://192.168.1.100:18789 (PID 12345)
✓ listening on ws://10.0.0.5:18789

セキュリティのヒント

⚠️ 非 loopback アドレスにバインドする場合は認証を設定する必要があります！

--bind lan / --bind tailnet の場合、--token または --password を渡す必要があります
そうしないと Gateway は起動を拒否し、次のエラーが表示されます：Refusing to bind gateway to lan without auth
認証トークンは gateway.auth.token 設定または --token パラメータで渡されます

ステップ 3：デーモンプロセスとしてインストールする（macOS / Linux / Windows）

理由

デーモンプロセスにすると、Gateway をバックグラウンドで実行でき、端末ウィンドウを閉じても影響を受けません。システム再起動後に自動的に起動し、AI アシスタントを常にオンラインに保ちます。

bash

# システムサービスとしてインストール（macOS LaunchAgent / Linux systemd / Windows Scheduled Task）
clawdbot gateway install

# サービスを起動
clawdbot gateway start

# サービスの状態を確認
clawdbot gateway status

# サービスを再起動
clawdbot gateway restart

# サービスを停止
clawdbot gateway stop

表示される内容：

bash

# macOS
✓ LaunchAgent loaded
✓ service runtime: active

# Linux
✓ systemd service enabled
✓ service runtime: active

# Windows
✓ Scheduled Task registered
✓ service runtime: running

チェックポイント

clawdbot gateway status を実行してサービスの状態が active / running であることを確認してください
サービスが loaded と表示されるが runtime: inactive の場合、clawdbot gateway start を実行してください
デーモンプロセスのログは ~/.clawdbot/logs/gateway.log に書き込まれます

ステップ 4：ポート競合を処理する（--force）

理由

デフォルトポート 18789 が他のプロセス（以前の Gateway インスタンスなど）によって使用されている可能性があります。--force を使用すると、ポートを自動的に解放できます。

bash

# ポートを強制的に解放して Gateway を起動
clawdbot gateway --force

表示される内容：

bash

✓ force: killed pid 9876 (node) on port 18789
✓ force: waited 1200ms for port 18789 to free
✓ agent model: anthropic/claude-opus-4-5
✓ listening on ws://127.0.0.1:18789 (PID 12345)

動作原理

--force は以下の操作を順次実行します：

SIGTERM でプロセスを正常に終了しようとする（700ms 待機）
終了しない場合、SIGKILL で強制的に終了
ポートの解放を待機（最大 2 秒）
新しい Gateway プロセスを起動

ステップ 5：開発モード（--dev）

理由

開発モードは独立した設定ファイルとディレクトリを使用するため、本番環境を汚染しません。TypeScript のホットリロードをサポートしており、コードを変更すると Gateway が自動的に再起動します。

bash

# 開発モードを起動（dev profile + workspace を作成）
clawdbot gateway --dev

# 開発設定をリセット（認証情報 + セッション + ワークスペースをクリア）
clawdbot gateway --dev --reset

表示される内容：

bash

✓ dev config created at ~/.clawdbot-dev/clawdbot.json
✓ dev workspace initialized at ~/clawd-dev
✓ agent model: anthropic/claude-opus-4-5
✓ listening on ws://127.0.0.1:18789 (PID 12345)

開発モードの特徴

設定ファイル：~/.clawdbot-dev/clawdbot.json（本番設定から独立）
ワークスペースディレクトリ：~/clawd-dev
BOOT.md スクリプトの実行をスキップ
デフォルトで loopback にバインドし、認証は不要

ステップ 6：Tailscale 統合

理由

Tailscale を使用すると、安全なプライベートネットワーク経由でリモート Gateway にアクセスでき、パブリック IP やポート転送が不要です。

bash

# Tailscale Serve モード（推奨）
clawdbot gateway --tailscale serve

# Tailscale Funnel モード（追加の認証が必要）
clawdbot gateway --tailscale funnel --auth password

表示される内容：

bash

# serve モード
✓ Tailscale identity detected
✓ advertising gateway via Tailscale Serve
✓ MagicDNS: https://your-tailnet.ts.net
✓ listening on ws://127.0.0.1:18789 (PID 12345)

# funnel モード
✓ Tailscale Funnel enabled
✓ Funnel URL: https://your-tailnet.ts.net:18789
✓ listening on ws://127.0.0.1:18789 (PID 12345)

認証の設定

Tailscale 統合は 2 つの認証方式をサポートしています：

Identity Headers（推奨）：gateway.auth.allowTailscale=true を設定すると、Tailscale ID が自動的に認証を満たします
Token / Password：従来の認証方式。手動で --token または --password を渡す必要があります

ステップ 7：Gateway の状態を確認する

理由

Gateway が正常に実行されており、RPC プロトコルにアクセス可能であることを確認します。

bash

# 完全な状態を表示（サービス + RPC プローブ）
clawdbot gateway status

# RPC プローブをスキップ（サービス状態のみ）
clawdbot gateway status --no-probe

# ヘルスチェック
clawdbot gateway health

# 到達可能なすべての Gateway をプローブ
clawdbot gateway probe

表示される内容：

bash

# status コマンドの出力
Gateway service status
┌──────────────────────────────────────┐
│ Service: LaunchAgent (loaded)      │
│ Runtime: running (PID 12345)       │
│ Port: 18789                       │
│ Last gateway error: none            │
└──────────────────────────────────────┘

RPC probe
┌──────────────────────────────────────┐
│ Target: ws://127.0.0.1:18789 │
│ Status: ✓ connected                │
│ Latency: 12ms                    │
└──────────────────────────────────────┘

# health コマンドの出力
✓ Gateway is healthy
✓ WebSocket connection: OK
✓ RPC methods: available

トラブルシューティング

status が Runtime: running と表示されるが RPC probe: failed と表示される場合：

ポートが正しいか確認：clawdbot gateway status
認証設定を確認：LAN / Tailnet にバインドされているが認証が提供されていない？
ログを確認：cat ~/.clawdbot/logs/gateway.log
clawdbot doctor を実行して詳細な診断を取得

落とし穴の警告

❌ エラー：Gateway の起動が拒否される

エラーメッセージ：

Gateway start blocked: set gateway.mode=local (current: unset) or pass --allow-unconfigured.

原因：gateway.mode が local に設定されていない

解決方法：

bash

# 方法 1：ウィザード設定を実行
clawdbot onboard

# 方法 2：設定ファイルを手動で変更
# ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "mode": "local"
  }
}

# 方法 3：一時的にチェックをスキップ（非推奨）
clawdbot gateway --allow-unconfigured

❌ エラー：LAN にバインドされているが認証がない

エラーメッセージ：

Refusing to bind gateway to lan without auth.
Set gateway.auth.token/password (or CLAWDBOT_GATEWAY_TOKEN/CLAWDBOT_GATEWAY_PASSWORD) or pass --token/--password.

原因：非 loopback バインドには認証設定が必要（セキュリティ制限）

解決方法：

bash

# 設定ファイルで認証を設定
# ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  }
}

# またはコマンドラインで渡す
clawdbot gateway --bind lan --token "your-secure-token"

❌ エラー：ポートが既に使用中

エラーメッセージ：

Error: listen EADDRINUSE: address already in use :::18789

原因：別の Gateway インスタンスまたは別のプログラムがポートを使用している

解決方法：

bash

# 方法 1：ポートを強制的に解放
clawdbot gateway --force

# 方法 2：別のポートを使用
clawdbot gateway --port 19001

# 方法 3：手動でプロセスを検索して終了
lsof -ti:18789 | xargs kill -9  # macOS / Linux
netstat -ano | findstr :18789               # Windows

❌ エラー：dev モードの reset には --dev が必要

エラーメッセージ：

Use --reset with --dev.

原因：--reset は開発モードでのみ使用可能。本番データの誤削除を防ぐため

解決方法：

bash

# 開発環境をリセットする正しいコマンド
clawdbot gateway --dev --reset

❌ エラー：サービスはインストール済みだがフォアグラウンドモードを使用している

現象：clawdbot gateway を実行すると「Gateway already running locally」と表示される

原因：デーモンプロセスが既にバックグラウンドで実行されている

解決方法：

bash

# バックグラウンドサービスを停止
clawdbot gateway stop

# またはサービスを再起動
clawdbot gateway restart

# その後フォアグラウンドを起動（デバッグが必要な場合）
clawdbot gateway --port 19001  # 別のポートを使用

本レッスンのまとめ

本レッスンでは以下を学習しました：

✅ 起動方法：フォアグラウンドモード vs デーモンプロセス ✅ バインディングモード：loopback / LAN / Tailnet / Auto ✅ 認証方式：Token / Password / Tailscale Identity ✅ 開発モード：独立設定、ホットリロード、--reset でのリセット ✅ トラブルシューティング：status / health / probe コマンド ✅ サービス管理：install / start / stop / restart / uninstall

主要コマンド早見表：

シナリオ	コマンド
日常使用（サービス）	`clawdbot gateway install && clawdbot gateway start`
開発デバッグ	`clawdbot gateway --dev`
一時テスト	`clawdbot gateway`
ポートの強制解放	`clawdbot gateway --force`
LAN アクセス	`clawdbot gateway --bind lan --token "xxx"`
Tailscale リモート	`clawdbot gateway --tailscale serve`
状態の確認	`clawdbot gateway status`
ヘルスチェック	`clawdbot gateway health`

次のレッスンの予告

次のレッスンでは 最初のメッセージを送信 を学習します。
学習内容：
WebChat を通じて最初のメッセージを送信する
設定済みチャンネル（WhatsApp/Telegram など）を通じて AI アシスタントと対話する
メッセージルーティングと応答フローを理解する

付録：ソースコード参考

クリックしてソースコードの場所を表示

更新日：2026-01-27

機能	ファイルパス	行号
Gateway 起動エントリー	`src/cli/gateway-cli/run.ts`	55-310
デーモンプロセスサービス抽象化	`src/daemon/service.ts`	66-155
サーバー起動サイドバー	`src/gateway/server-startup.ts`	26-160
Gateway サーバー実装	`src/gateway/server.ts`	1-500
プログラム引数解析	`src/daemon/program-args.ts`	1-250
起動ログ出力	`src/gateway/server-startup-log.ts`	7-40
開発モード設定	`src/cli/gateway-cli/dev.ts`	1-100
ポート解放ロジック	`src/cli/ports.ts`	1-80

主要定数：

デフォルトポート：18789（出所：src/gateway/server.ts）
デフォルトバインド：loopback（出所：src/cli/gateway-cli/run.ts:175）
開発モード設定パス：~/.clawdbot-dev/（出所：src/cli/gateway-cli/dev.ts）

主要関数：

runGatewayCommand()：Gateway CLI のメインエントリー、コマンドライン引数と起動ロジックを処理
startGatewayServer()：WebSocket サーバーを起動し、指定ポートをリスン
forceFreePortAndWait()：ポートを強制的に解放して待機
resolveGatewayService()：プラットフォームに基づいて対応するデーモンプロセス実装を返す（macOS LaunchAgent / Linux systemd / Windows Scheduled Task）
logGatewayStartup()：Gateway 起動情報（モデル、リスンアドレス、ログファイル）を出力

ゼロから始める

一般的なチャットツールへの接続

AI の超能力をアンロック

問題が発生したら

起動する Gateway：デーモンプロセスと実行モード

学習後の目標

現在の課題

いつ使用するか

🎒 開始前の準備

コアコンセプト

手順を追って

ステップ 1：Gateway を起動する（フォアグラウンドモード）

ステップ 2：バインディングモードを設定する

ステップ 3：デーモンプロセスとしてインストールする（macOS / Linux / Windows）

ステップ 4：ポート競合を処理する（--force）

ステップ 5：開発モード（--dev）

ステップ 6：Tailscale 統合

ステップ 7：Gateway の状態を確認する

落とし穴の警告

❌ エラー：Gateway の起動が拒否される

❌ エラー：LAN にバインドされているが認証がない

❌ エラー：ポートが既に使用中

❌ エラー：dev モードの reset には --dev が必要

❌ エラー：サービスはインストール済みだがフォアグラウンドモードを使用している

本レッスンのまとめ

次のレッスンの予告

付録：ソースコード参考

起動する Gateway：デーモンプロセスと実行モード ​

学習後の目標 ​

現在の課題 ​

いつ使用するか ​

🎒 開始前の準備 ​

コアコンセプト ​

手順を追って ​

ステップ 1：Gateway を起動する（フォアグラウンドモード） ​

ステップ 2：バインディングモードを設定する ​

ステップ 3：デーモンプロセスとしてインストールする（macOS / Linux / Windows） ​

ステップ 4：ポート競合を処理する（--force） ​

ステップ 5：開発モード（--dev） ​

ステップ 6：Tailscale 統合 ​

ステップ 7：Gateway の状態を確認する ​

落とし穴の警告 ​

❌ エラー：Gateway の起動が拒否される ​

❌ エラー：LAN にバインドされているが認証がない ​

❌ エラー：ポートが既に使用中 ​

❌ エラー：dev モードの reset には --dev が必要 ​

❌ エラー：サービスはインストール済みだがフォアグラウンドモードを使用している ​

本レッスンのまとめ ​

次のレッスンの予告 ​

付録：ソースコード参考 ​

起動する Gateway：デーモンプロセスと実行モード

学習後の目標

現在の課題

いつ使用するか

🎒 開始前の準備

コアコンセプト

手順を追って

ステップ 1：Gateway を起動する（フォアグラウンドモード）

ステップ 2：バインディングモードを設定する

ステップ 3：デーモンプロセスとしてインストールする（macOS / Linux / Windows）

ステップ 4：ポート競合を処理する（--force）

ステップ 5：開発モード（--dev）

ステップ 6：Tailscale 統合

ステップ 7：Gateway の状態を確認する

落とし穴の警告

❌ エラー：Gateway の起動が拒否される

❌ エラー：LAN にバインドされているが認証がない

❌ エラー：ポートが既に使用中

❌ エラー：dev モードの reset には --dev が必要

❌ エラー：サービスはインストール済みだがフォアグラウンドモードを使用している

本レッスンのまとめ

次のレッスンの予告

付録：ソースコード参考