> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# TCPモード

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

## TCPモード

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

## TCPモードのメリット

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

## 使い方

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

```shell theme={null}
copilot --headless --port 12345
```

### 2. 環境変数を設定

```dotenv theme={null}
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 接続を設定できます。

```php theme={null}
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 モードかが自動で選ばれます。
コード内で明示的に切り替えることも可能です。

```php theme={null}
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 環境では不要な場合があります。

```shell theme={null}
sudo supervisorctl restart daemon-123456:*
```

### Laravel Cloud

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

詳しくは [Laravel Cloudでの使い方](/jp/packages/laravel-copilot-sdk/laravel-cloud) を参照してください。

## 注意事項

### セキュリティ

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

### 再接続

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

### 現在モードの確認

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

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

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

### 接続できない

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

```shell theme={null}
ps aux | grep copilot
```

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

```shell theme={null}
netstat -an | grep 12345
```

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

### タイムアウトエラー

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

```php theme={null}
'timeout' => 120, // 2分
```

<Info>
  最新情報は [GitHub リポジトリ](https://github.com/invokable/laravel-copilot-sdk) を参照してください。
</Info>