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 archivoAlcanceDescripción
~/.pi/agent/settings.jsonGlobal (todos los proyectos)Configuración general aplicable a todos los proyectos
.pi/settings.jsonNivel de proyectoSolo 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ónTipoValor predeterminadoDescripción
defaultProviderstring-Proveedor predeterminado, como "anthropic", "openai"
defaultModelstring-ID de modelo predeterminado
defaultThinkingLevelstring-Nivel de inferencia predeterminado, valores posibles: off / minimal / low / medium / high / xhigh / max
hideThinkingBlockbooleanfalseOcultar el razonamiento de IA por defecto
showCacheMissNoticesbooleanfalseMostrar aviso de fallo de caché
thinkingBudgetsobject-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:

NivelEscenario aplicablePresupuesto de ejemplo
minimalCasi sin razonamiento, busca la respuesta más rápida1024
lowPreguntas y respuestas sencillas y cambios menores4096
mediumOpción predeterminada para tareas de codificación diarias10240
highRefactorización compleja y resolución de problemas difíciles32768

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ónTipoValor predeterminadoDescripción
themestring"dark"Nombre del tema
externalEditorstringSelección automática según el sistemaComando del editor externo que se abre con Ctrl+G
quietStartupbooleanfalseOcultar la información de cabecera de inicio
collapseChangelogbooleanfalseMostrar o no el registro de cambios plegado después de una actualización
editorPaddingXnumber0Relleno horizontal del editor (0-3)
outputPadnumber1Relleno horizontal del área de mensajes (0 o 1)
autocompleteMaxVisiblenumber5Má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ónTipoValor predeterminadoDescripción
httpProxystring-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ónTipoValor predeterminadoDescripción
compaction.enabledbooleantrueHabilitar compresión automática
compaction.reserveTokensnumber16384Tokens reservados para la respuesta del LLM
compaction.keepRecentTokensnumber20000Nú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ónTipoValor predeterminadoDescripción
retry.enabledbooleantrueHabilitar reintento automático
retry.maxRetriesnumber3Número máximo de reintentos
retry.baseDelayMsnumber2000Retraso base de reintento (milisegundos), retroceso exponencial: 2 s, 4 s, 8 s
retry.provider.timeoutMsnumberPredeterminado del SDKTiempo de espera de solicitud (milisegundos)
retry.provider.maxRetriesnumber0Nú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ónTipoValor predeterminadoDescripción
steeringModestring"one-at-a-time"Política de envío de mensajes steering: "all" o "one-at-a-time"
followUpModestring"one-at-a-time"Política de envío de mensajes follow-up
transportstring"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ónTipoValor predeterminadoDescripción
terminal.showImagesbooleantrueMostrar imágenes en la terminal
terminal.imageWidthCellsnumber60Ancho de imagen incrustada (celdas de terminal)
images.autoResizebooleantrueRedimensionar la imagen a un máximo de 2000x2000
images.blockImagesbooleanfalseBloquear 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ónTipoValor predeterminadoDescripción
shellPathstring-Ruta personalizada del shell
shellCommandPrefixstring-Prefijo para cada comando bash
npmCommandstring[]-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ónTipoValor predeterminadoDescripción
enabledModelsstring[]-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