TCP-Modus

Beschreibt, wie Sie sich im Laravel Copilot SDK mit einem vorab gestarteten Copilot-CLI-Server verbinden und ihn mit geringem Overhead gemeinsam nutzen.

​

TCP-Modus

Standardmäßig startet das SDK bei jeder Anfrage einen neuen Copilot-CLI-Prozess (stdio-Modus). Im TCP-Modus können Sie sich stattdessen mit einem zuvor gestarteten Copilot-CLI-Server verbinden.

​

Vorteile des TCP-Modus

• Bessere Performance: Kein Overhead durch das Starten von Prozessen
• Ressourcen-Sharing: Mehrere Laravel-Prozesse können denselben CLI-Server nutzen
• Prozessverwaltung: Als Hintergrundprozess über Laravel Forge / Laravel Cloud verwaltbar
• Deployment-Unterstützung: Automatischer Neustart beim Deployment möglich

​

Verwendung

​

1. Copilot-CLI-Server starten

copilot --headless --port 12345

​

2. Umgebungsvariablen setzen

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

Damit wechselt das SDK automatisch vom stdio- in den TCP-Modus.

• tcp:// ist optional. Auch http:// oder ganz ohne Schema funktioniert.
• Die reine Angabe eines Ports ist möglich. In diesem Fall wird 127.0.0.1 als Host verwendet.
• Reine Host-Angaben sind nur mit 127.0.0.1 oder localhost gültig. In diesem Fall lautet der Standardport 12345.

​

Konfigurationsdatei

Die TCP-Verbindung konfigurieren Sie in config/copilot.php.

return [
    // TCP-Ziel-URL (die Angabe schaltet in den TCP-Modus)
    'url' => env('COPILOT_URL'),

    // Die folgenden Werte werden nur im stdio-Modus verwendet
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Für beide Modi gültig
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];

Sind sowohl COPILOT_URL (cli_url) als auch COPILOT_CLI_PATH gesetzt, hat der TCP-Modus Vorrang.

​

Moduswechsel zur Laufzeit

Normalerweise wird der Modus (TCP oder stdio) anhand der Konfigurationsdatei automatisch gewählt. Sie können ihn im Code jedoch auch explizit wechseln.

use Revolution\Copilot\Facades\Copilot;

// In den TCP-Modus wechseln
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Bei Weglassen wird der Wert aus der Konfigurationsdatei verwendet
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// In den stdio-Modus wechseln
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// Bei Weglassen wird der Wert aus der Konfigurationsdatei verwendet
// Da bei beiden gesetzten Modi TCP Vorrang hat, ist dies für temporäres Überschreiben nützlich
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');

Auf manchen Servern arbeitet der TCP-Modus nicht zuverlässig. Es ist auch möglich, Queue-Jobs im TCP-Modus und Verarbeitung innerhalb von HTTP-Anfragen im stdio-Modus zu betreiben.

​

Betrieb mit Laravel Forge / Laravel Cloud

​

Laravel Forge

1. Daemon erstellen: Erstellen Sie im Forge-Backend einen Daemon.

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

2. Umgebungsvariablen setzen: Ergänzen Sie COPILOT_URL in .env.

3. Beim Deployment neu starten: Starten Sie den Daemon aus dem Deploy-Skript neu.

In aktuellen Forge-Umgebungen ist dies unter Umständen nicht mehr erforderlich.

sudo supervisorctl restart daemon-123456:*

​

Laravel Cloud

Mit der Worker-Funktion von Laravel Cloud können Sie den Copilot-CLI-Server als Hintergrundprozess betreiben.

Details finden Sie unter Nutzung mit Laravel Cloud.

​

Hinweise

​

Sicherheit

Verwenden Sie für den TCP-Server möglichst ein lokales Binding (127.0.0.1). Beim externen Bereitstellen konfigurieren Sie die Firewall angemessen.

​

Wiederverbindung

Die aktuelle Version verfügt nicht über automatisches Reconnect. Bricht die Verbindung ab, wird eine Ausnahme geworfen.

​

Aktuellen Modus prüfen

Innerhalb des Programms können Sie prüfen, in welchem Modus der Client arbeitet.

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

if ($client->isTcpMode()) {
    // TCP-Modus
} else {
    // stdio-Modus
}

​

Troubleshooting

​

Verbindung schlägt fehl

1. Prüfen, ob der Copilot-CLI-Server läuft

ps aux | grep copilot

2. Prüfen, ob der Port korrekt ist

netstat -an | grep 12345

3. Firewall-Einstellungen prüfen

​

Timeout-Fehler

Erhöhen Sie den timeout-Wert in config/copilot.php.

'timeout' => 120, // 2 Minuten

Aktuelle Informationen finden Sie im GitHub-Repository.