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

# Referencia de opciones del cliente

> Referencia de todas las opciones del cliente de Laravel Copilot SDK, con su valor por defecto, su variable de entorno y su comportamiento al conectarse en modo TCP.

## Referencia de opciones del cliente

El cliente se configura en `config/copilot.php`.
También puedes pasar las mismas opciones como array a `Copilot::client()`, `useStdio()` / `useTcp()` o `new Client([...])`.
Esta página enumera las opciones del fichero de configuración y las opciones que solo puedes pasar desde el código.

## Opciones del fichero de configuración

| Opción | Valor por defecto | Variable de entorno | Modo TCP |
| - | - | - | - |
| `mode` | `'copilot-cli'` | `COPILOT_MODE` | Compartida |
| `url` | `null` | `COPILOT_URL` | Al definirla se activa el modo TCP |
| `cli_path` | `'copilot'` | `COPILOT_CLI_PATH` | Ignorada |
| `cli_args` | `[]` | - | Ignorada |
| `cwd` | `null` (ruta base de la app) | - | Ignorada |
| `log_level` | `'info'` | `COPILOT_LOG_LEVEL` | Ignorada |
| `builtin_plugin_directories` | `[]` | - | Compartida |
| `timeout` | `60.0` | `COPILOT_TIMEOUT` | Compartida |
| `model` | `null` | `COPILOT_MODEL` | Compartida |
| `copilot_home` | `null` | `COPILOT_HOME` | Ignorada |
| `base_directory` | `null` | `COPILOT_BASE_DIRECTORY` | Ignorada |
| `session_fs` | `null` | - | Compartida |
| `permission_approve` | `'deny-all'` | `COPILOT_PERMISSION_APPROVE` | Compartida (capa Facade) |
| `telemetry` | `null` | - | Ignorada |
| `session_idle_timeout_seconds` | `0` | `COPILOT_SESSION_IDLE_TIMEOUT` | Ignorada |
| `request_handler` | `null` | - | Compartida |

### Conexión

* `mode`: el modo del cliente, `'copilot-cli'` (normal) o `'empty'`. `empty` desactiva las funciones implícitas de la CLI. En este modo debes definir explícitamente un directorio base, SessionFs o una URL TCP.
* `url`: la URL de un servidor de Copilot CLI existente (por ejemplo `tcp://127.0.0.1:12345`). Si la defines, el SDK se conecta a ese servidor en lugar de iniciar un nuevo proceso de la CLI. Consulta [Modo TCP](https://kawax.biz/es/packages/laravel-copilot-sdk/tcp-mode.md) para más detalles.
* `cli_path`: la ruta al ejecutable de la CLI. Defínela como `null` para localizar la CLI automáticamente.
* `cli_args`: argumentos adicionales que se pasan al iniciar la CLI (por ejemplo `['--yolo']`).
* `cwd`: el directorio de trabajo del proceso de la CLI.
* `log_level`: el nivel de log del servidor de la CLI. Elige entre `none`, `error`, `warning`, `info`, `debug` o `all`.

### Valores por defecto

* `timeout`: el timeout por defecto en segundos de `sendAndWait()`. `Copilot::run()` también lo usa.
* `model`: el modelo por defecto cuando creas una sesión sin especificar ninguno.
* `permission_approve`: cómo se gestionan automáticamente las solicitudes de permiso cuando usas la Facade (`Copilot::run()` y similares). Elige `'deny-all'` (denegar todo), `'approve-safety'` (aprobar todo excepto shell y write), `'approve-all'` (aprobar todo) o `false` (no inyectar un handler). Cuando usas el Client directamente, siempre se requiere un handler `onPermissionRequest`. Consulta [Solicitudes de permiso](https://kawax.biz/es/packages/laravel-copilot-sdk/permission-request.md) para más detalles.

### Ubicación de los datos

* `copilot_home`: el directorio base de los datos de Copilot (estado de sesión y ajustes). El SDK lo pasa al proceso de la CLI que inicia como variable de entorno `COPILOT_HOME`. Si no se define, se aplica el valor por defecto de la CLI (`~/.copilot`).
* `base_directory`: un alias de `copilot_home` con el nombre del SDK oficial. Si defines ambos, prevalece `base_directory`.
* `session_fs`: los ajustes de un proveedor SessionFs que delega el estado de sesión (ficheros y SQLite) a tu propio almacenamiento. `initialCwd`, `sessionStatePath` y `conventions` son obligatorios. Si lo defines, cada sesión también debe especificar `createSessionFsProvider`.
* `builtin_plugin_directories`: un array de rutas absolutas a directorios de plugins integrados de confianza. El SDK los registra en el runtime cuando se inicia el cliente. Consulta [Plugin Directories](https://kawax.biz/es/packages/laravel-copilot-sdk/plugin-directories.md) para más detalles.

### Otras opciones

* `telemetry`: un array de ajustes de OpenTelemetry (`otlpEndpoint`, `filePath`, `exporterType`, `sourceName`, `captureContent`). El SDK lo convierte en variables de entorno para el proceso de la CLI que inicia. Consulta [Telemetry](https://kawax.biz/es/packages/laravel-copilot-sdk/telemetry.md) para más detalles.
* `session_idle_timeout_seconds`: el timeout de inactividad de sesiones para todo el servidor, en segundos. `0` (el valor por defecto) lo desactiva, por lo que las sesiones permanecen activas indefinidamente.
* `request_handler`: un `CopilotRequestHandler` o closure que intercepta las solicitudes HTTP a la capa del modelo (experimental). No se aplica a las solicitudes WebSocket.

## Opciones que no están en el fichero de configuración

Las siguientes opciones no están en el fichero de configuración, pero puedes pasarlas como argumentos a `useStdio()`, `Copilot::client()` o `new Client([...])`.

| Opción | Descripción | Modo TCP |
| - | - | - |
| `env` | Un array de variables de entorno adicionales que se pasan al proceso de la CLI que inicia el SDK | Ignorada |
| `github_token` | El token de GitHub usado para la autenticación | No permitida |
| `use_logged_in_user` | Si se usa el usuario que ya ha iniciado sesión en la CLI | No permitida |
| `installation_confirmation_handler` | Un callback que confirma la instalación de la CLI | Ignorada |
| `entra` | Ajustes de autenticación de Microsoft Entra (`EntraAuthConfig` o un array) | Compartida |
| `on_github_telemetry` | Un callback que recibe las notificaciones de telemetría de GitHub | Compartida |
| `extension_launch_provider` | Un callback que resuelve cómo se inician las extensiones | Compartida |
| `network` | Ajustes del proxy de red del sandbox (`scope`, `resolveProxy`, `authenticateNegotiate`) | Compartida |

No puedes usar `github_token` ni `use_logged_in_user` en modo TCP, porque el servidor externo gestiona su propia autenticación.
Si defines cualquiera de las dos y te conectas por TCP, el SDK lanza una excepción.
Para cambiar de token en tiempo de ejecución, consulta también [Token de GitHub](https://kawax.biz/es/packages/laravel-copilot-sdk/github-token.md).

Muchas opciones aceptan nombres tanto en snake\_case como en camelCase (por ejemplo `session_fs` y `sessionFs`, `builtin_plugin_directories` y `builtinPluginDirectories`, `request_handler` y `requestHandler`).


## Related topics

- [Uso de la capa de compatibilidad con el SDK oficial](https://kawax.biz/es/packages/laravel-copilot-sdk/bare-usage.md)
- [Modo TCP](https://kawax.biz/es/packages/laravel-copilot-sdk/tcp-mode.md)
- [Laravel LSP — extensión de funciones del IDE mediante Language Server Protocol](https://kawax.biz/es/blog/laravel-lsp-introduction.md)
- [Cliente HTTP y pruebas en paquetes](https://kawax.biz/es/advanced/package-http-client.md)
- [Referencia de API - VOICEVOX Core for PHP](https://kawax.biz/es/packages/voicevox-core-php/api.md)


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