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
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!');
Laravel Forge / Laravel Cloud에서의 운영
Laravel Forge
-
Daemon 작성: Forge 관리 화면에서 Daemon을 작성합니다.
Command: copilot --headless --port 12345
User: forge
Directory: /home/forge/your-app
-
환경 변수 설정:
.env에 COPILOT_URL을 추가합니다.
-
배포 시 재시작: 배포 스크립트에서 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 모드
}
트러블슈팅
접속할 수 없음
- Copilot CLI 서버가 기동되어 있는지 확인
- 포트가 올바른지 확인
- 방화벽 설정 확인
타임아웃 에러
config/copilot.php의 timeout 값을 늘려 주세요.
