> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 클라이언트 옵션 목록

> Laravel Copilot SDK의 모든 클라이언트 옵션에 대해 기본값, 환경 변수, TCP 모드로 연결할 때의 동작을 정리한 레퍼런스입니다.

## 클라이언트 옵션 목록

클라이언트는 `config/copilot.php`에서 설정합니다.
같은 옵션을 배열로 `Copilot::client()`, `useStdio()` / `useTcp()`, `new Client([...])`에 전달할 수도 있습니다.
이 페이지에서는 설정 파일의 옵션과 코드에서만 전달할 수 있는 옵션을 정리합니다.

## 설정 파일의 옵션

| 옵션 | 기본값 | 환경 변수 | TCP 모드 |
| - | - | - | - |
| `mode` | `'copilot-cli'` | `COPILOT_MODE` | 공통 |
| `url` | `null` | `COPILOT_URL` | 설정하면 TCP 모드가 됨 |
| `cli_path` | `'copilot'` | `COPILOT_CLI_PATH` | 무시됨 |
| `cli_args` | `[]` | - | 무시됨 |
| `cwd` | `null` (앱의 base path) | - | 무시됨 |
| `log_level` | `'info'` | `COPILOT_LOG_LEVEL` | 무시됨 |
| `builtin_plugin_directories` | `[]` | - | 공통 |
| `timeout` | `60.0` | `COPILOT_TIMEOUT` | 공통 |
| `model` | `null` | `COPILOT_MODEL` | 공통 |
| `copilot_home` | `null` | `COPILOT_HOME` | 무시됨 |
| `base_directory` | `null` | `COPILOT_BASE_DIRECTORY` | 무시됨 |
| `session_fs` | `null` | - | 공통 |
| `permission_approve` | `'deny-all'` | `COPILOT_PERMISSION_APPROVE` | 공통 (Facade 레이어) |
| `telemetry` | `null` | - | 무시됨 |
| `session_idle_timeout_seconds` | `0` | `COPILOT_SESSION_IDLE_TIMEOUT` | 무시됨 |
| `request_handler` | `null` | - | 공통 |

### 연결

* `mode`: 클라이언트 모드입니다. `'copilot-cli'`(일반) 또는 `'empty'`를 지정합니다. `empty`는 CLI의 암묵적인 기능을 비활성화합니다. 이 모드에서는 base directory, SessionFs, TCP URL 중 하나를 명시적으로 설정해야 합니다.
* `url`: 기존 Copilot CLI 서버의 URL입니다(예: `tcp://127.0.0.1:12345`). 설정하면 SDK는 새 CLI 프로세스를 시작하지 않고 이 서버에 연결합니다. 자세한 내용은 [TCP 모드](https://kawax.biz/ko/packages/laravel-copilot-sdk/tcp-mode.md)를 참조하세요.
* `cli_path`: CLI 실행 파일의 경로입니다. `null`로 설정하면 CLI를 자동으로 찾습니다.
* `cli_args`: CLI 시작 시 전달할 추가 인수입니다(예: `['--yolo']`).
* `cwd`: CLI 프로세스의 작업 디렉터리입니다.
* `log_level`: CLI 서버의 로그 레벨입니다. `none`, `error`, `warning`, `info`, `debug`, `all` 중에서 선택합니다.

### 기본값

* `timeout`: `sendAndWait()`의 기본 타임아웃(초)입니다. `Copilot::run()`도 이 값을 사용합니다.
* `model`: 모델을 지정하지 않고 세션을 만들 때의 기본 모델입니다.
* `permission_approve`: Facade(`Copilot::run()` 등)를 사용할 때 권한 요청을 자동으로 처리하는 방법입니다. `'deny-all'`(모두 거부), `'approve-safety'`(shell과 write를 제외하고 모두 승인), `'approve-all'`(모두 승인), `false`(핸들러를 주입하지 않음) 중에서 선택합니다. Client를 직접 사용할 때는 항상 `onPermissionRequest` 핸들러가 필요합니다. 자세한 내용은 [권한 요청](https://kawax.biz/ko/packages/laravel-copilot-sdk/permission-request.md)을 참조하세요.

### 데이터 저장 위치

* `copilot_home`: Copilot 데이터(세션 상태와 설정)의 기본 디렉터리입니다. SDK는 시작하는 CLI 프로세스에 `COPILOT_HOME` 환경 변수로 전달합니다. 설정하지 않으면 CLI의 기본값(`~/.copilot`)이 적용됩니다.
* `base_directory`: 공식 SDK의 이름을 사용하는 `copilot_home`의 별칭입니다. 둘 다 설정하면 `base_directory`가 우선됩니다.
* `session_fs`: 세션 상태(파일과 SQLite)를 직접 만든 스토리지에 위임하는 SessionFs 프로바이더의 설정입니다. `initialCwd`, `sessionStatePath`, `conventions`는 필수입니다. 설정하면 각 세션에서도 `createSessionFsProvider`를 지정해야 합니다.
* `builtin_plugin_directories`: 신뢰할 수 있는 내장 플러그인 디렉터리의 절대 경로 배열입니다. SDK는 클라이언트 시작 시 이를 런타임에 등록합니다. 자세한 내용은 [Plugin Directories](https://kawax.biz/ko/packages/laravel-copilot-sdk/plugin-directories.md)를 참조하세요.

### 기타 옵션

* `telemetry`: OpenTelemetry 설정 배열입니다(`otlpEndpoint`, `filePath`, `exporterType`, `sourceName`, `captureContent`). SDK는 이를 시작하는 CLI 프로세스의 환경 변수로 변환합니다. 자세한 내용은 [Telemetry](https://kawax.biz/ko/packages/laravel-copilot-sdk/telemetry.md)를 참조하세요.
* `session_idle_timeout_seconds`: 서버 전체에 적용되는 세션 유휴 타임아웃(초)입니다. `0`(기본값)이면 비활성화되어 세션이 무기한 유지됩니다.
* `request_handler`: 모델 레이어로 가는 HTTP 요청을 가로채는 `CopilotRequestHandler` 또는 클로저입니다(experimental). WebSocket 요청에는 적용되지 않습니다.

## 설정 파일에 없는 옵션

다음 옵션은 설정 파일에는 없지만 `useStdio()`, `Copilot::client()`, `new Client([...])`의 인수로 전달할 수 있습니다.

| 옵션 | 설명 | TCP 모드 |
| - | - | - |
| `env` | SDK가 시작하는 CLI 프로세스에 전달할 추가 환경 변수 배열 | 무시됨 |
| `github_token` | 인증에 사용할 GitHub 토큰 | 사용 불가 |
| `use_logged_in_user` | CLI에 이미 로그인한 사용자를 사용할지 여부 | 사용 불가 |
| `installation_confirmation_handler` | CLI 설치를 확인하는 콜백 | 무시됨 |
| `entra` | Microsoft Entra 인증 설정(`EntraAuthConfig` 또는 배열) | 공통 |
| `on_github_telemetry` | GitHub 텔레메트리 알림을 받는 콜백 | 공통 |
| `extension_launch_provider` | 확장 기능의 실행 방법을 결정하는 콜백 | 공통 |
| `network` | 샌드박스 네트워크 프록시 설정(`scope`, `resolveProxy`, `authenticateNegotiate`) | 공통 |

외부 서버가 자체 인증을 관리하므로 TCP 모드에서는 `github_token`과 `use_logged_in_user`를 사용할 수 없습니다.
둘 중 하나를 설정한 상태로 TCP로 연결하면 SDK가 예외를 던집니다.
실행 중 토큰 전환에 대해서는 [GitHub 토큰](https://kawax.biz/ko/packages/laravel-copilot-sdk/github-token.md)도 참조하세요.

많은 옵션은 snake\_case와 camelCase 이름을 모두 받습니다(예: `session_fs`와 `sessionFs`, `builtin_plugin_directories`와 `builtinPluginDirectories`, `request_handler`와 `requestHandler`).


## Related topics

- [TCP 모드](https://kawax.biz/ko/packages/laravel-copilot-sdk/tcp-mode.md)
- [공식 SDK 호환 레이어 사용법](https://kawax.biz/ko/packages/laravel-copilot-sdk/bare-usage.md)
- [HTTP 클라이언트](https://kawax.biz/ko/http-client.md)
- [클라이언트 모드 - 프리셋 - VOICEVOX for Laravel](https://kawax.biz/ko/packages/laravel-voicevox/client-presets.md)
- [패키지의 HTTP 클라이언트와 테스트](https://kawax.biz/ko/advanced/package-http-client.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.