TCP 모드

Laravel Copilot SDK에서 미리 기동한 Copilot CLI 서버에 접속하여 낮은 오버헤드로 공유 운영하는 방법을 설명합니다.

​

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

1. Daemon 작성: Forge 관리 화면에서 Daemon을 작성합니다.

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

2. 환경 변수 설정: .env에 COPILOT_URL을 추가합니다.

3. 배포 시 재시작: 배포 스크립트에서 Daemon을 재시작합니다.

현재 Forge 환경에서는 불필요한 경우가 있습니다.

sudo supervisorctl restart daemon-123456:*

​

Laravel Cloud

Laravel Cloud의 워커 기능을 사용해 백그라운드 프로세스로 실행할 수 있습니다.

자세한 내용은 Laravel Cloud에서의 사용법을 참고하세요.

​

주의사항

​

보안

TCP 서버는 가능한 한 로컬 바인드(127.0.0.1)를 사용하세요. 외부에 공개할 경우 방화벽 설정을 적절히 해주세요.

​

재접속

현재 버전에는 자동 재접속 기능이 없습니다. 접속이 끊어지면 예외가 던져집니다.

​

현재 모드 확인

프로그램 내에서 클라이언트가 어떤 모드인지 확인할 수 있습니다.

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

​

트러블슈팅

​

접속할 수 없음

1. Copilot CLI 서버가 기동되어 있는지 확인

ps aux | grep copilot

2. 포트가 올바른지 확인

netstat -an | grep 12345

3. 방화벽 설정 확인

​

타임아웃 에러

config/copilot.php의 timeout 값을 늘려 주세요.

'timeout' => 120, // 2분

최신 정보는 GitHub 저장소를 참고하세요.