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

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

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

環境変数を設定: .env に COPILOT_URL を追加します。
デプロイ時に再起動: デプロイスクリプトで Daemon を再起動します。

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

sudo supervisorctl restart daemon-123456:*

Laravel Cloud

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

注意事項

セキュリティ

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

再接続

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

接続の終了と起動エラー

Client::stop() は stdio モードでは SDK が起動したランタイムを停止します。TCP モードでは共有サーバーを停止せず、クライアントの接続だけを閉じます。 stdio の起動ハンドシェイクがタイムアウトした場合、例外には直近 8 KiB までのプロセス stderr が含まれます。診断出力には機密情報が含まれる可能性があるため、外部へ記録する前に内容を確認してください。

現在モードの確認

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

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

トラブルシューティング

接続できない

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

ps aux | grep copilot

ポートが正しいか確認

netstat -an | grep 12345

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

タイムアウトエラー

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

'timeout' => 120, // 2分

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

GitHub Copilot

SDK

AI SDK

VOICEVOX

スターターキット

フィード・RSS

ミドルウェア

TCPモード

TCPモード

TCPモードのメリット

使い方

1. Copilot CLIサーバーを起動

2. 環境変数を設定

設定ファイル

実行時のモード切り替え

Laravel Forge / Laravel Cloudでの運用

Laravel Forge

Laravel Cloud

注意事項

セキュリティ

再接続

接続の終了と起動エラー

現在モードの確認

トラブルシューティング

接続できない

タイムアウトエラー

​TCPモード

​TCPモードのメリット

​使い方

​1. Copilot CLIサーバーを起動

​2. 環境変数を設定

​設定ファイル

​実行時のモード切り替え

​Laravel Forge / Laravel Cloudでの運用

​Laravel Forge

​Laravel Cloud

​注意事項

​セキュリティ

​再接続

​接続の終了と起動エラー

​現在モードの確認

​トラブルシューティング

​接続できない

​タイムアウトエラー

TCPモード

TCPモードのメリット

使い方

1. Copilot CLIサーバーを起動

2. 環境変数を設定

設定ファイル

実行時のモード切り替え

Laravel Forge / Laravel Cloudでの運用

Laravel Forge

Laravel Cloud

注意事項

セキュリティ

再接続

接続の終了と起動エラー

現在モードの確認

トラブルシューティング

接続できない

タイムアウトエラー