Vai al contenuto principale

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

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.
  • 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.

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.

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.
  • 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([...]). 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. 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).
Ultima modifica il 16 novembre 2026