Saltar al contenido principal

​
Modo TCP

Normalmente el SDK arranca un nuevo proceso de Copilot CLI por cada petición (modo stdio). Con el modo TCP puedes conectar a un servidor Copilot CLI arrancado previamente.

​
Ventajas del modo TCP

  • Mejor rendimiento: no hay overhead de arranque de proceso
  • Recursos compartidos: varios procesos Laravel pueden compartir el mismo servidor CLI
  • Gestión de procesos: puedes gestionarlo como proceso en segundo plano con Laravel Forge / Laravel Cloud
  • Compatible con despliegues: soporta el reinicio automático en cada despliegue

​
Uso

​
1. Arranca el servidor Copilot CLI

copilot --headless --port 12345

​
2. Configura la variable de entorno

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 solo esto, el SDK pasa automáticamente de stdio a TCP.
  • tcp:// es opcional. Funciona también con http:// o sin esquema.
  • Puedes indicar solo el puerto; en ese caso el host es 127.0.0.1 de forma automática.
  • Si indicas solo el host, únicamente son válidos 127.0.0.1 y localhost; en ese caso el puerto por defecto es 12345.

​
Fichero de configuración

Puedes configurar la conexión TCP en config/copilot.php. 
return [
    // URL de destino de la conexión TCP (si se configura, se usa el modo TCP)
    'url' => env('COPILOT_URL'),

    // Lo siguiente solo se usa en modo stdio
    'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
    'cli_args' => [],
    'cwd' => null,
    'log_level' => env('COPILOT_LOG_LEVEL', 'info'),

    // Común a ambos modos
    'timeout' => env('COPILOT_TIMEOUT', 60),
    'model' => env('COPILOT_MODEL'),
];
Si defines tanto COPILOT_URL (cli_url) como COPILOT_CLI_PATH, tiene prioridad el modo TCP.

​
Cambio de modo en tiempo de ejecución

Normalmente se elige automáticamente TCP o stdio según el fichero de configuración. También puedes cambiarlo explícitamente en el código. 
use Revolution\Copilot\Facades\Copilot;

// Cambia a modo TCP
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// Si lo omites, usa el valor del fichero de configuración
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');

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

// Si lo omites, usa el valor del fichero de configuración
// Si tienes ambos modos configurados, como TCP tiene prioridad, sirve para hacer una sobreescritura temporal
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');
Según el servidor, es posible que el modo TCP no funcione correctamente. También puedes usarlo de forma mixta: modo TCP para procesos en cola y modo stdio para procesos dentro de peticiones HTTP.

​
Operar en Laravel Forge / Laravel Cloud

​
Laravel Forge

  1. Crea un Daemon: crea un Daemon en el panel de Forge. 
    Command: copilot --headless --port 12345
User: forge
Directory: /home/forge/your-app
  2. Configura la variable de entorno: añade COPILOT_URL en .env.
  3. Reinicia en el despliegue: reinicia el Daemon en el script de despliegue.
Puede no ser necesario en las versiones actuales de Forge. 
sudo supervisorctl restart daemon-123456:*

​
Laravel Cloud

Puedes ejecutarlo como proceso en segundo plano con la funcionalidad de workers de Laravel Cloud. Consulta Uso en Laravel Cloud para más detalles.

​
Consideraciones

​
Seguridad

Siempre que sea posible, haz que el servidor TCP escuche localmente (127.0.0.1). Si vas a exponerlo al exterior, configura el firewall adecuadamente.

​
Reconexión

La versión actual no tiene reconexión automática. Si se pierde la conexión, se lanza una excepción.

​
Comprobar el modo actual

Puedes comprobar en qué modo está el cliente desde el programa. 
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

​
Solución de problemas

​
No se puede conectar

  1. Comprueba que el servidor Copilot CLI está arrancado
ps aux | grep copilot
  1. Comprueba que el puerto es correcto
netstat -an | grep 12345
  1. Revisa la configuración del firewall

​
Error de timeout

Aumenta el valor de timeout en config/copilot.php. 
'timeout' => 120, // 2 minutos
Consulta la información más reciente en el repositorio de GitHub.
Última modificación el 13 de julio de 2026

Temas relacionados

Token de GitHubLaravel Cloud - GitHub Copilot SDK for LaravelEventos del ciclo de vida de sesiónRemote SessionsConcurrency