Detalles de configuración de Pi Agent
Pi Agent utiliza archivos de configuración en formato JSON, compatible con configuración global y configuración a nivel de proyecto.
Ubicación del archivo de configuración
Pi Agent lee la configuración desde dos rutas fijas, con diferentes prioridades.
| Ruta de archivo | Alcance | Descripción |
|---|---|---|
| ~/.pi/agent/settings.json | Global (todos los proyectos) | Configuración general aplicable a todos los proyectos |
| .pi/settings.json | Nivel de proyecto | Solo afecta al proyecto actual y sobrescribe la configuración global |
Puede editar directamente el archivo JSON, o usar el comando en el modo interactivo/settingscomando para modificar opciones comunes.
Configuración de modelo e inferencia
Los siguientes elementos de configuración controlan qué proveedor y qué modelo se usan por defecto, y cómo se distribuye el presupuesto de inferencia.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| defaultProvider | string | - | Proveedor predeterminado, como "anthropic", "openai" |
| defaultModel | string | - | ID de modelo predeterminado |
| defaultThinkingLevel | string | - | Nivel de inferencia predeterminado, valores posibles: off / minimal / low / medium / high / xhigh / max |
| hideThinkingBlock | boolean | false | Ocultar el razonamiento de IA por defecto |
| showCacheMissNotices | boolean | false | Mostrar aviso de fallo de caché |
| thinkingBudgets | object | - | Personalizar el presupuesto de tokens para cada nivel |
Ejemplo de personalización del presupuesto de inferencia:
Ejemplo
"thinkingBudgets": {
"minimal": 1024,
"low": 4096,
"medium": 10240,
"high": 32768
}
}
Cabe señalar que los siguientes valores son solo para demostración, no son valores predeterminados oficiales.
La correspondencia entre el significado de cada nivel y el presupuesto de ejemplo es la siguiente:
| Nivel | Escenario aplicable | Presupuesto de ejemplo |
|---|---|---|
| minimal | Casi sin razonamiento, busca la respuesta más rápida | 1024 |
| low | Preguntas y respuestas sencillas y cambios menores | 4096 |
| medium | Opción predeterminada para tareas de codificación diarias | 10240 |
| high | Refactorización compleja y resolución de problemas difíciles | 32768 |
Configuración de interfaz y visualización
Los siguientes elementos de configuración controlan la apariencia del tema, el diseño del editor y el comportamiento de inicio.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| theme | string | "dark" | Nombre del tema |
| externalEditor | string | Selección automática según el sistema | Comando del editor externo que se abre con Ctrl+G |
| quietStartup | boolean | false | Ocultar la información de cabecera de inicio |
| collapseChangelog | boolean | false | Mostrar o no el registro de cambios plegado después de una actualización |
| editorPaddingX | number | 0 | Relleno horizontal del editor (0-3) |
| outputPad | number | 1 | Relleno horizontal del área de mensajes (0 o 1) |
| autocompleteMaxVisible | number | 5 | Máximo de entradas visibles en el autocompletado (3-20) |
Configuración de editor externo recomendada para usuarios de VS Code:
Ejemplo
"externalEditor": "code --wait"
}
--waitEl parámetro asegura que Pi Agent reanude la ejecución solo después de que VS Code cierre el archivo; de lo contrario, Pi Agent continuará inmediatamente después de que el editor se abra.
Configuración de red
Los siguientes elementos de configuración controlan el proxy que utiliza Pi Agent al acceder a la API del modelo.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| httpProxy | string | - | URL del proxy HTTP (solo configuración global) |
Configurar el proxy (adecuado para entornos como China continental que requieren proxy para acceder a la API):
Ejemplo
"httpProxy": "http://127.0.0.1:7890"
}
Configuración de compresión de contexto
Cuando el contexto se acerca al límite, Pi Agent comprime automáticamente los mensajes históricos; aquí se controla la activación de la compresión y la política de retención.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| compaction.enabled | boolean | true | Habilitar compresión automática |
| compaction.reserveTokens | number | 16384 | Tokens reservados para la respuesta del LLM |
| compaction.keepRecentTokens | number | 20000 | Número de tokens recientes que se conservan sin comprimir |
Configuración de reintentos
Los siguientes elementos de configuración determinan el comportamiento de reintento automático después de un fallo de solicitud, incluido el número de reintentos y el intervalo de retroceso.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| retry.enabled | boolean | true | Habilitar reintento automático |
| retry.maxRetries | number | 3 | Número máximo de reintentos |
| retry.baseDelayMs | number | 2000 | Retraso base de reintento (milisegundos), retroceso exponencial: 2 s, 4 s, 8 s |
| retry.provider.timeoutMs | number | Predeterminado del SDK | Tiempo de espera de solicitud (milisegundos) |
| retry.provider.maxRetries | number | 0 | Número de reintentos a nivel de proveedor |
Se recomienda mantenerretry.provider.maxRetriesen 0, a menos que realmente necesites reintentos a nivel de proveedor.
Establecer un valor mayor que 0 puede hacer que los reintentos a nivel de SDK bloqueen a Pi Agent cuando se supera el límite de uso, en lugar de permitir que el mecanismo de reintentos de Pi Agent lo maneje.
Configuración de envío de mensajes
Los siguientes elementos de configuración controlan cuándo y de qué manera se envían al modelo los mensajes que insertas en la conversación.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| steeringMode | string | "one-at-a-time" | Política de envío de mensajes steering: "all" o "one-at-a-time" |
| followUpMode | string | "one-at-a-time" | Política de envío de mensajes follow-up |
| transport | string | "auto" | Protocolo de transporte: "sse", "websocket", "websocket-cached", "auto" |
Configuración de terminal e imágenes
Los siguientes elementos de configuración controlan cómo se muestran las imágenes en la terminal y la estrategia de procesamiento antes de enviarlas al modelo.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| terminal.showImages | boolean | true | Mostrar imágenes en la terminal |
| terminal.imageWidthCells | number | 60 | Ancho de imagen incrustada (celdas de terminal) |
| images.autoResize | boolean | true | Redimensionar la imagen a un máximo de 2000x2000 |
| images.blockImages | boolean | false | Bloquear el envío de todas las imágenes al LLM |
Configuración de Shell
Los siguientes elementos de configuración controlan el shell y el prefijo de comando que utiliza Pi Agent al ejecutar comandos bash.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| shellPath | string | - | Ruta personalizada del shell |
| shellCommandPrefix | string | - | Prefijo para cada comando bash |
| npmCommand | string[] | - | Comando personalizado para operaciones de paquetes npm |
Ejemplo de uso de herramientas como mise o asdf para gestionar la versión de Node.js:
Ejemplo
"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
Configuración de ciclo de modelos
Los siguientes elementos de configuración controlan qué modelos se pueden ver al alternar modelos con Ctrl+P.
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| enabledModels | string[] | - | Lista de modelos disponibles en el ciclo Ctrl+P, admite comodines |
Ejemplo
"enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}
Reglas de fusión de configuración
La configuración del proyecto (.pi/settings.json) sobrescribe la configuración global (~/.pi/agent/settings.json).
Los objetos anidados utilizanfusiónen lugar de una estrategia de reemplazo; a continuación se explica con un ejemplo.
Archivo de configuración global ~/.pi/agent/settings.json:
Ejemplo
"theme": "dark",
"compaction": { "enabled": true, "reserveTokens": 16384 }
}
Archivo de configuración del proyecto .pi/settings.json:
Ejemplo
"compaction": { "reserveTokens": 8192 }
}
En la configuración efectiva después de la fusión, theme toma el valor global dark, compaction.enabled toma el valor global true, y compaction.reserveTokens se sobrescribe a 8192 por la configuración del proyecto.
Es decir, la configuración del proyecto solo sobrescribe los campos que declara explícitamente; el resto de campos continúan usando la configuración global.
Ejemplo de configuración completa
A continuación se muestra un archivo de configuración global típico:
Ejemplo
"defaultProvider": "anthropic",
"defaultModel": "claude-sonnet-4-20250514",
"defaultThinkingLevel": "medium",
"theme": "dark",
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
},
"retry": {
"enabled": true,
"maxRetries": 3
},
"enabledModels": ["claude-*", "gpt-4o"],
"warnings": {
"anthropicExtraUsage": true
},
"packages": ["pi-skills"]
}
warnings.anthropicExtraUsage es un valor booleano, por defecto true.
Muestra una advertencia cuando la autenticación de la suscripción de Anthropic pueda generar un uso adicional de pago.
packages es la configuración de filtro de paquetes instalados, utilizada para declarar los paquetes que se cargarán.
Otras extensiones