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

# Riferimento delle opzioni del client

> Riferimento di tutte le opzioni del client di Laravel Copilot SDK, con valore di default, variabile d'ambiente e comportamento quando ti connetti in modalità TCP.

## Riferimento delle opzioni del client

Il client si configura in `config/copilot.php`.
Puoi anche passare le stesse opzioni come array a `Copilot::client()`, `useStdio()` / `useTcp()` o `new Client([...])`.
Questa pagina elenca le opzioni del file di configurazione e quelle che puoi passare solo dal codice.

## Opzioni del file di configurazione

| Opzione | Default | Variabile d'ambiente | Modalità TCP |
| - | - | - | - |
| `mode` | `'copilot-cli'` | `COPILOT_MODE` | Condivisa |
| `url` | `null` | `COPILOT_URL` | Impostarla attiva la modalità TCP |
| `cli_path` | `'copilot'` | `COPILOT_CLI_PATH` | Ignorata |
| `cli_args` | `[]` | - | Ignorata |
| `cwd` | `null` (percorso base dell'app) | - | Ignorata |
| `log_level` | `'info'` | `COPILOT_LOG_LEVEL` | Ignorata |
| `builtin_plugin_directories` | `[]` | - | Condivisa |
| `timeout` | `60.0` | `COPILOT_TIMEOUT` | Condivisa |
| `model` | `null` | `COPILOT_MODEL` | Condivisa |
| `copilot_home` | `null` | `COPILOT_HOME` | Ignorata |
| `base_directory` | `null` | `COPILOT_BASE_DIRECTORY` | Ignorata |
| `session_fs` | `null` | - | Condivisa |
| `permission_approve` | `'deny-all'` | `COPILOT_PERMISSION_APPROVE` | Condivisa (livello Facade) |
| `telemetry` | `null` | - | Ignorata |
| `session_idle_timeout_seconds` | `0` | `COPILOT_SESSION_IDLE_TIMEOUT` | Ignorata |
| `request_handler` | `null` | - | Condivisa |

### Connessione

* `mode`: la modalità del client, `'copilot-cli'` (normale) o `'empty'`. `empty` disattiva le funzionalità implicite della CLI. In questa modalità devi impostare esplicitamente una directory base, SessionFs o un URL TCP.
* `url`: l'URL di un server Copilot CLI esistente (ad esempio `tcp://127.0.0.1:12345`). Se lo imposti, l'SDK si connette a questo server invece di avviare un nuovo processo della CLI. Per i dettagli consulta [Modalità TCP](https://kawax.biz/it/packages/laravel-copilot-sdk/tcp-mode.md).
* `cli_path`: il percorso dell'eseguibile della CLI. Impostalo a `null` per individuare la CLI automaticamente.
* `cli_args`: argomenti aggiuntivi passati all'avvio della CLI (ad esempio `['--yolo']`).
* `cwd`: la directory di lavoro del processo della CLI.
* `log_level`: il livello di log del server della CLI. Scegli tra `none`, `error`, `warning`, `info`, `debug` o `all`.

### Valori di default

* `timeout`: il timeout di default in secondi per `sendAndWait()`. Lo usa anche `Copilot::run()`.
* `model`: il modello di default quando crei una sessione senza specificarne uno.
* `permission_approve`: come vengono gestite automaticamente le richieste di permesso quando usi la Facade (`Copilot::run()` e simili). Scegli `'deny-all'` (nega tutto), `'approve-safety'` (approva tutto tranne shell e write), `'approve-all'` (approva tutto) o `false` (non iniettare un handler). Quando usi direttamente il Client, è sempre richiesto un handler `onPermissionRequest`. Per i dettagli consulta [Richieste di permesso](https://kawax.biz/it/packages/laravel-copilot-sdk/permission-request.md).

### Posizione dei dati

* `copilot_home`: la directory base dei dati di Copilot (stato delle sessioni e impostazioni). L'SDK la passa al processo della CLI che avvia come variabile d'ambiente `COPILOT_HOME`. Se non è impostata, si applica il default della CLI (`~/.copilot`).
* `base_directory`: un alias di `copilot_home` che usa il nome dell'SDK ufficiale. Se imposti entrambe, prevale `base_directory`.
* `session_fs`: le impostazioni di un provider SessionFs che delega lo stato delle sessioni (file e SQLite) al tuo storage. `initialCwd`, `sessionStatePath` e `conventions` sono obbligatori. Se lo imposti, ogni sessione deve anche specificare `createSessionFsProvider`.
* `builtin_plugin_directories`: un array di percorsi assoluti verso directory di plugin integrati attendibili. L'SDK le registra nel runtime all'avvio del client. Per i dettagli consulta [Plugin Directories](https://kawax.biz/it/packages/laravel-copilot-sdk/plugin-directories.md).

### Altre opzioni

* `telemetry`: un array di impostazioni OpenTelemetry (`otlpEndpoint`, `filePath`, `exporterType`, `sourceName`, `captureContent`). L'SDK lo converte in variabili d'ambiente per il processo della CLI che avvia. Per i dettagli consulta [Telemetria](https://kawax.biz/it/packages/laravel-copilot-sdk/telemetry.md).
* `session_idle_timeout_seconds`: il timeout di inattività delle sessioni a livello di server, in secondi. `0` (il default) lo disattiva, quindi le sessioni restano attive a tempo indeterminato.
* `request_handler`: un `CopilotRequestHandler` o una closure che intercetta le richieste HTTP verso il livello del modello (sperimentale). Non si applica alle richieste WebSocket.

## Opzioni non presenti nel file di configurazione

Le seguenti opzioni non sono nel file di configurazione, ma puoi passarle come argomenti a `useStdio()`, `Copilot::client()` o `new Client([...])`.

| Opzione | Descrizione | Modalità TCP |
| - | - | - |
| `env` | Un array di variabili d'ambiente aggiuntive passate al processo della CLI avviato dall'SDK | Ignorata |
| `github_token` | Il token GitHub usato per l'autenticazione | Non consentita |
| `use_logged_in_user` | Se usare l'utente che ha già effettuato l'accesso alla CLI | Non consentita |
| `installation_confirmation_handler` | Una callback che conferma l'installazione della CLI | Ignorata |
| `entra` | Impostazioni di autenticazione Microsoft Entra (`EntraAuthConfig` o un array) | Condivisa |
| `on_github_telemetry` | Una callback che riceve le notifiche di telemetria di GitHub | Condivisa |
| `extension_launch_provider` | Una callback che determina come vengono avviate le estensioni | Condivisa |
| `network` | Impostazioni del proxy di rete della sandbox (`scope`, `resolveProxy`, `authenticateNegotiate`) | Condivisa |

Non puoi usare `github_token` o `use_logged_in_user` in modalità TCP, perché il server esterno gestisce la propria autenticazione.
Se ne imposti una e ti connetti via TCP, l'SDK lancia un'eccezione.
Per cambiare token a runtime, consulta anche [Token GitHub](https://kawax.biz/it/packages/laravel-copilot-sdk/github-token.md).

Molte opzioni accettano sia nomi in snake\_case sia in camelCase (ad esempio `session_fs` e `sessionFs`, `builtin_plugin_directories` e `builtinPluginDirectories`, `request_handler` e `requestHandler`).


## Related topics

- [Uso dello strato di compatibilità con l'SDK ufficiale](https://kawax.biz/it/packages/laravel-copilot-sdk/bare-usage.md)
- [Modalità TCP](https://kawax.biz/it/packages/laravel-copilot-sdk/tcp-mode.md)
- [HTTP Client](https://kawax.biz/it/http-client.md)
- [Struttura delle directory](https://kawax.biz/it/directory-structure.md)
- [Riferimento della configurazione - VOICEVOX for Laravel](https://kawax.biz/it/packages/laravel-voicevox/configuration.md)


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