TCPモード

Laravel Copilot SDK で事前起動した Copilot CLI サーバーへ接続し、低オーバーヘッドで共有運用する方法を説明します。

​

TCPモード

通常、SDK は各リクエストごとに新しい Copilot CLI プロセスを起動します（stdio モード）。 TCP モードを使うと、事前に起動した Copilot CLI サーバーへ接続できます。

​

TCPモードのメリット

• パフォーマンス向上: プロセス起動オーバーヘッドがない
• リソース共有: 複数の Laravel プロセスで同一 CLI サーバーを共有できる
• プロセス管理: Laravel Forge / Laravel Cloud でバックグラウンドプロセスとして管理できる
• デプロイ対応: デプロイ時の自動再起動に対応できる

​

使い方

​

1. Copilot CLIサーバーを起動

copilot --headless --port 12345

​

2. 環境変数を設定

COPILOT_URL=tcp://127.0.0.1:12345
# COPILOT_URL=http://127.0.0.1:12345
# COPILOT_URL=127.0.0.1:12345
# COPILOT_URL=12345
# COPILOT_URL=127.0.0.1
# COPILOT_URL=localhost

これだけで、SDK は stdio モードから TCP モードに自動で切り替わります。

• tcp:// は任意です。http:// やスキームなしでも動作します。
• ポートだけの指定も可能です。その場合ホストは自動で 127.0.0.1 になります。
• ホストだけの指定は 127.0.0.1 と localhost のみ有効です。その場合ポートはデフォルト 12345 になります。

​

設定ファイル

config/copilot.php で TCP 接続を設定できます。

return [
    // TCP接続先URL（設定するとTCPモードになる）
    'url' => env('COPILOT_URL'),

    // 以下はstdioモード時のみ使用される
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // 両モード共通
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];

COPILOT_URL（cli_url）と COPILOT_CLI_PATH を両方設定した場合は TCP モードが優先されます。

​

実行時のモード切り替え

通常は設定ファイルに従って TCP モードか stdio モードかが自動で選ばれます。 コード内で明示的に切り替えることも可能です。

use Revolution\Copilot\Facades\Copilot;

// TCPモードに切り替える
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// 省略時は設定ファイルの値を使う
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// stdioモードに切り替える
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// 省略時は設定ファイルの値を使う
// 両モードを設定している場合はTCPが優先なので、一時的な上書きに使える
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');

サーバーによっては TCP モードで正常に動作しないことがあります。 キュー処理は TCP モード、HTTP リクエスト内の処理は stdio モードのように使い分けることも可能です。

​

Laravel Forge / Laravel Cloudでの運用

​

Laravel Forge

1. Daemon を作成: Forge 管理画面で Daemon を作成します。

   Command: copilot --headless --port 12345
   User: forge
   Directory: /home/forge/your-app
   

2. 環境変数を設定: .env に COPILOT_URL を追加します。

3. デプロイ時に再起動: デプロイスクリプトで Daemon を再起動します。

現在の Forge 環境では不要な場合があります。

sudo supervisorctl restart daemon-123456:*

​

Laravel Cloud

Laravel Cloud のワーカー機能を使い、バックグラウンドプロセスとして実行できます。

詳しくは Laravel Cloudでの使い方 を参照してください。

​

注意事項

​

セキュリティ

TCPサーバーは可能な限りローカルバインド（127.0.0.1）を使ってください。 外部公開する場合はファイアウォール設定を適切に行ってください。

​

再接続

現在のバージョンには自動再接続機能がありません。接続が切れると例外がスローされます。

​

現在モードの確認

プログラム内でクライアントがどちらのモードか確認できます。

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

if ($client->isTcpMode()) {
    // TCPモード
} else {
    // stdioモード
}

​

トラブルシューティング

​

接続できない

1. Copilot CLI サーバーが起動しているか確認

ps aux | grep copilot

2. ポートが正しいか確認

netstat -an | grep 12345

3. ファイアウォール設定を確認

​

タイムアウトエラー

config/copilot.php の timeout 値を増やしてください。

'timeout' => 120, // 2分

最新情報は GitHub リポジトリ を参照してください。