Manual de referencia de configuración de Pi Agent
La siguiente es una tabla de referencia rápida de los elementos de configuración de settings.json de Pi Agent.
Esta tabla incluye los elementos de configuración más comunes; algunas claves avanzadas específicas de JSON (como tuiMode, la serie fullscreen, terminal.hyperlinks, markdown.mermaid, etc.) no se enumeran individualmente.
Ubicación del archivo de configuración
La configuración se divide en dos niveles: global y de proyecto. La configuración de proyecto solo se carga después de obtener la confianza del proyecto.
| Ruta del archivo | Alcance | Descripción |
|---|---|---|
| ~/.pi/agent/settings.json | Global (todos los proyectos) | Configuración general que aplica a todos los proyectos |
| .pi/settings.json | Nivel de proyecto | Se carga solo después de que el proyecto obtenga confianza y sobrescribe las claves con el mismo nombre en la configuración global. |
Modelo e inferencia
La configuración de esta sección determina el proveedor, el modelo y la intensidad de inferencia utilizados por defecto.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| defaultProvider | string | Opcional | Ninguno (se establece la primera vez mediante /login o /model) | Proveedor predeterminado, como "anthropic", "openai" |
| defaultModel | string | Opcional | Ninguno (se establece la primera vez mediante /login o /model) | ID del modelo predeterminado, como "claude-sonnet-4-20250514" |
| defaultThinkingLevel | string | Opcional | Ninguno (no se indica en la documentación) | Nivel de inferencia predeterminado: off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | object | Opcional | Ninguno | Establece el nivel de inferencia de inicio para cada modelo según "provider/modelId" |
| hideThinkingBlock | boolean | Opcional | false | Ocultar el proceso de razonamiento |
| showCacheMissNotices | boolean | Opcional | false | Mostrar aviso de fallo de caché |
| thinkingBudgets | object | Opcional | Ninguno (presupuesto personalizado no habilitado) | Presupuesto de tokens personalizado para cada nivel |
| warnings.anthropicExtraUsage | boolean | Opcional | true | Avisar cuando la suscripción de Anthropic pueda generar uso adicional de pago |
UI y visualización
La configuración de esta sección controla la apariencia de la interfaz, el editor externo y la densidad de visualización.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| theme | string | Opcional | "dark" | Nombre del tema |
| externalEditor | string | Opcional | Toma $VISUAL y $EDITOR en ese orden; de lo contrario, usa Notepad en Windows y nano en otros sistemas. | Comando del editor externo (la configuración explícita tiene prioridad sobre las variables de entorno) |
| quietStartup | boolean | Opcional | false | Ocultar el encabezado de inicio |
| defaultProjectTrust | string | Opcional | "ask" | Comportamiento predeterminado de confianza del proyecto: "ask" (preguntar), "always" (confiar automáticamente), "never" (rechazar automáticamente); solo aplica en la configuración global. |
| collapseChangelog | boolean | Opcional | false | Contraer el registro de cambios |
| enableInstallTelemetry | boolean | Opcional | true | Estadísticas de instalación anónimas |
| enableAnalytics | boolean | Opcional | false | Análisis de comportamiento del usuario (requiere activación explícita) |
| doubleEscapeAction | string | Opcional | "tree" | Acción activada al pulsar Escape dos veces; por defecto abre el explorador del árbol de sesiones |
| treeFilterMode | string | Opcional | "default" | Modo de filtrado predeterminado de /tree: default/no-tools/user-only/labeled-only/all |
| editorPaddingX | number | Opcional | 0 | Relleno horizontal del editor (0-3) |
| outputPad | number | Opcional | 1 | Relleno de los mensajes (0 o 1) |
| autocompleteMaxVisible | number | Opcional | 5 | Número máximo de elementos de autocompletado (3-20) |
Red
La configuración de esta sección se utiliza para el acceso mediante proxy en entornos de red restringidos.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| httpProxy | string | Opcional | Ninguno (no se usa proxy) | Proxy HTTP (solo global) |
httpProxySolo aplica en la configuración global; no tiene efecto si se escribe en la configuración de nivel de proyecto.
Cuando necesite un proxy, escríbalo en~/.pi/agent/settings.json。
Compresión
La configuración de esta sección controla la activación de la compresión automática del contexto y la política de retención.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| compaction.enabled | boolean | Opcional | true | Compresión automática |
| compaction.reserveTokens | number | Opcional | 16384 | Tokens reservados para la respuesta del LLM |
| compaction.keepRecentTokens | number | Opcional | 20000 | Tokens recientes conservados |
Resumen de ramas
La configuración de esta sección controla si se genera un resumen de las ramas abandonadas al saltar entre árboles de sesión.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| branchSummary.reserveTokens | number | Opcional | 16384 | Tokens reservados para el resumen |
| branchSummary.skipPrompt | boolean | Opcional | false | Omitir el aviso de resumen |
Reintentos
La configuración de esta sección controla el comportamiento de reintento automático tras fallos de solicitud.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| retry.enabled | boolean | Opcional | true | Reintento automático |
| retry.maxRetries | number | Opcional | 3 | Número máximo de reintentos |
| retry.baseDelayMs | number | Opcional | 2000 | Retardo base (ms) |
| retry.provider.timeoutMs | number | Opcional | Predeterminado del SDK | Tiempo de espera de solicitud |
| retry.provider.maxRetries | number | Opcional | 0 | Número de reintentos a nivel de proveedor |
| retry.provider.maxRetryDelayMs | number | Opcional | 60000 | Retardo máximo de reintento |
Mensajería
La configuración de esta sección determina cómo se insertan los mensajes de orientación y seguimiento, así como el protocolo de transporte utilizado.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| steeringMode | string | Opcional | "one-at-a-time" | Política de mensajes de orientación: "all" (todos los mensajes de orientación se insertan de inmediato) o "one-at-a-time" (se insertan uno a uno) |
| followUpMode | string | Opcional | "one-at-a-time" | Política de mensajes de seguimiento |
| transport | string | Opcional | "auto" | Protocolo de transporte: sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | number | Opcional | 300000 | Tiempo de espera de inactividad HTTP |
| websocketConnectTimeoutMs | number | Opcional | 15000 | Tiempo de espera de conexión WebSocket |
Terminal e imágenes
La configuración de esta sección controla el tamaño de visualización y el comportamiento de envío de las imágenes en la terminal.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| terminal.showImages | boolean | Opcional | true | Mostrar imágenes en la terminal |
| terminal.imageWidthCells | number | Opcional | 60 | Ancho de la imagen (celdas) |
| terminal.clearOnShrink | boolean | Opcional | false | Limpiar líneas vacías cuando el contenido se contrae |
| images.autoResize | boolean | Opcional | true | Escalado automático de imágenes |
| images.blockImages | boolean | Opcional | false | Bloquear el envío de imágenes al LLM |
Shell
La configuración de esta sección se utiliza para personalizar el shell y el envoltorio de npm al ejecutar comandos.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| shellPath | string | Opcional | Ninguno (se usa el shell predeterminado del sistema) | Ruta personalizada del shell |
| shellCommandPrefix | string | Opcional | Ninguno (sin prefijo) | Prefijo de comando |
| npmCommand | string[] | Opcional | Ninguno (se llama directamente a npm) | Envoltorio de comandos npm |
Herramientas integradas
La configuración de esta sección controla el conjunto de herramientas integradas habilitadas por defecto al iniciar.
| Elemento de configuración | Tipo | ¿Requerido? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| defaultTools | string[] | Opcional | Ninguno (se usa el conjunto de herramientas integrado predeterminado) | Herramientas integradas habilitadas inicialmente, valores opcionales read/bash/powershell/edit/write/grep/find/ls, donde powershell solo está disponible en Windows |
Esta configuración solo afecta a las herramientas integradas; las herramientas personalizadas registradas por extensiones y SDK no se ven afectadas.
La matriz defaultTools a nivel de proyecto reemplaza por completo a la matriz global.
Bucle del modelo y recursos
Esta sección configura el alcance del bucle de modelos de Ctrl+P, así como las rutas de carga de recursos como extensiones y Skills.
| Elemento de configuración | Tipo | ¿Es obligatorio? | Valor predeterminado | Descripción |
|---|---|---|---|---|
| enabledModels | string[] | Opcional | Ninguno (todos los modelos disponibles) | Modelos disponibles en Ctrl+P |
| packages | array (mixto de cadenas u objetos) | Opcional | [] | Origen del paquete; en forma de cadena carga todos los recursos, en forma de objeto filtra mediante campos como {source, skills, extensions} |
| extensions | string[] | Opcional | [] | Ruta de extensiones |
| skills | string[] | Opcional | [] | Ruta de Skills |
| prompts | string[] | Opcional | [] | Ruta de plantillas |
| themes | string[] | Opcional | [] | Ruta de temas |
| enableSkillCommands | boolean | Opcional | true | Registrar el comando /skill:name |
| sessionDir | string | Opcional | Ninguno (usar ~/.pi/agent/sessions/) | Directorio de almacenamiento de sesiones |