Saltar al contenido principal

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

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 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 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 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 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([...]). 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. 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).
Última modificación el 16 de noviembre de 2026