Vai al contenuto principale

​
Modalità TCP

Di norma l’SDK avvia un nuovo processo Copilot CLI per ogni richiesta (modalità stdio). Con la modalità TCP puoi connetterti a un server Copilot CLI avviato in anticipo.

​
Vantaggi della modalità TCP

  • Miglioramento delle performance: nessun overhead di avvio processo
  • Condivisione delle risorse: più processi Laravel possono condividere lo stesso server CLI
  • Gestione del processo: gestibile come processo in background con Laravel Forge / Laravel Cloud
  • Adatto al deploy: supporta il riavvio automatico durante il deploy

​
Uso

​
1. Avvia il server Copilot CLI

copilot --headless --port 12345

​
2. Imposta la variabile d’ambiente

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
Con questo, l’SDK passa automaticamente da stdio a TCP.
  • tcp:// è opzionale. Funziona anche con http:// o senza schema.
  • Puoi specificare solo la porta. In tal caso l’host è automaticamente 127.0.0.1.
  • La specifica del solo host è valida solo per 127.0.0.1 e localhost. In tal caso la porta di default è 12345.

​
File di configurazione

Puoi configurare la connessione TCP in config/copilot.php. 
return [
    // URL di destinazione TCP (se impostato attiva la modalità TCP)
    'url' => env('COPILOT_URL'),

    // I successivi vengono usati solo in modalità stdio
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Comune a entrambe le modalità
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];
Se imposti sia COPILOT_URL (cli_url) sia COPILOT_CLI_PATH, ha priorità la modalità TCP.

​
Cambio di modalità a runtime

Di norma la modalità TCP o stdio viene scelta automaticamente in base al file di configurazione. Puoi anche cambiarla esplicitamente nel codice. 
use Revolution\Copilot\Facades\Copilot;

// Passa alla modalità TCP
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Se omessa, usa il valore del file di configurazione
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

// Passa alla modalità stdio
$stdioConfig = [
    'cli_path' => 'copilot',
    'cli_args' => [],
    'cwd' => base_path(),
    'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');

// Se omesso, usa il valore del file di configurazione
// Se sono impostate entrambe le modalità ha priorità TCP, quindi è utile per un override temporaneo
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');
Con alcuni server la modalità TCP potrebbe non funzionare correttamente. È anche possibile alternare: modalità TCP per le queue, modalità stdio all’interno delle richieste HTTP.

​
Uso con Laravel Forge / Laravel Cloud

​
Laravel Forge

  1. Crea un Daemon: crea un Daemon dalla dashboard Forge. 
    Command: copilot --headless --port 12345
User: forge
Directory: /home/forge/your-app
  2. Imposta la variabile d’ambiente: aggiungi COPILOT_URL in .env.
  3. Riavvio al deploy: riavvia il Daemon nello script di deploy.
Con l’attuale ambiente Forge potrebbe non essere necessario. 
sudo supervisorctl restart daemon-123456:*

​
Laravel Cloud

Puoi eseguirlo come processo in background usando la funzionalità worker di Laravel Cloud. Per i dettagli consulta Uso su Laravel Cloud.

​
Note

​
Sicurezza

Usa per quanto possibile il bind locale (127.0.0.1) per il server TCP. Se lo esponi pubblicamente, configura in modo appropriato il firewall.

​
Riconnessione

La versione attuale non ha una riconnessione automatica. Se la connessione cade viene sollevata un’eccezione.

​
Verifica della modalità corrente

Nel codice puoi verificare in che modalità è il client. 
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

​
Troubleshooting

​
Connessione fallita

  1. Verifica che il server Copilot CLI sia in esecuzione
ps aux | grep copilot
  1. Verifica che la porta sia corretta
netstat -an | grep 12345
  1. Verifica la configurazione del firewall

​
Errore di timeout

Aumenta il valore di timeout in config/copilot.php. 
'timeout' => 120, // 2 minuti
Per le informazioni più recenti fai riferimento al repository GitHub.
Ultima modifica il 13 luglio 2026

Argomenti correlati

ConcurrencyLaravel Cloud - GitHub Copilot SDK for LaravelEventi del ciclo di vita della sessioneToken GitHubAutenticazione - GitHub Copilot SDK for Laravel