Instala PI con Ollama y Kimi-K2.5, configura subagentes, autoresearch y personaliza tu propio coding agent. Guía paso a paso para todos los niveles.

Detrás de OpenClaw, el popular agente de codificación de Ollama, existe un núcleo más pequeño y poderoso: PI (pi-coding-agent), un terminal coding harness de código abierto diseñado para ser la base sobre la que se construyen agentes de IA personalizados. Su filosofía es opuesta a la de herramientas como Claude Code: parte de un núcleo mínimo —aproximadamente 200 tokens de system prompt y solo 4 herramientas nativas— y delega toda la personalización al usuario mediante extensiones, skills, plantillas y temas (MOGE, 2026). Ollama ahora permite lanzar PI directamente desde la terminal con un solo comando, configurando automáticamente el proveedor, las herramientas web y el soporte multimodal.

¿Qué es PI y cómo se relaciona con OpenClaw?

PI es la infraestructura base que alimenta a OpenClaw: todo lo que OpenClaw puede hacer, PI lo construye desde cero mediante su sistema de extensiones. La diferencia es que OpenClaw viene preconfigurado para uso inmediato, mientras que PI es la versión desnuda para quienes prefieren controlar cada detalle del comportamiento del agente (Lucumr, 2026). Esto lo convierte en la opción ideal tanto para uso diario ligero como para investigadores y equipos que necesitan construir flujos de trabajo de agentes muy específicos.

• Núcleo mínimo: ~200 tokens de system prompt, 4 herramientas nativas, arquitectura deliberadamente simple (MOGE, 2026).
• +15 proveedores: Anthropic, OpenAI, Google, Azure, Mistral, Groq, Cerebras, xAI, Hugging Face, Bedrock y más (MOGE, 2026).
• Lanzable desde Ollama: Un solo comando instala PI, configura Ollama como proveedor e incluye herramientas web y soporte multimodal (Ollama, 2026).
• Sesiones tipo árbol: Arquitectura de historial que permite bifurcar y navegar entre conversaciones como ramas de Git (AICodeKing, 2026).
• SDK embebible: PI puede integrarse como librería en aplicaciones propias mediante modo RPC (MOGE, 2026).

Kimi-K2.5: el modelo recomendado para PI con Ollama

El modelo sugerido por Ollama para lanzar PI es Kimi-K2.5, desarrollado por Moonshot AI. Se trata de un modelo multimodal nativo de código abierto entrenado con aproximadamente 15 billones de tokens visuales y de texto, con capacidades de razonamiento agentico avanzado, modo instantáneo y modo de thinking (Ollama, 2026). Lo que resulta particularmente interesante es su tecnología Agent Swarm: K2.5 puede descomponer tareas complejas en subtareas paralelas ejecutadas por agentes especializados coordinados dinámicamente (Codecademy, 2026).

• Multimodalidad nativa: Genera código a partir de especificaciones visuales como diseños de UI o flujos de video (Ollama, 2026).
• Agent Swarm: Transición de agente único a esquema de ejecución paralela con agentes de dominio específico (Codecademy, 2026).
• INT4 nativo: Cuantización integrada en el entrenamiento para velocidad 2x sin degradación de precisión vs FP16 (Codecademy, 2026).
• Disponible en la nube de Ollama como kimi-k2.5:cloud, sin necesidad de correrlo localmente (requeriría más de 240 GB de RAM para rendimiento adecuado) (Unsloth, 2026).

Requisitos previos

Antes de ejecutar cualquier comando, verifica que el entorno cumpla estos requisitos para evitar errores durante la instalación:

• Node.js 18+: Verifica con node --version. Descarga desde nodejs.org si no está instalado.
• npm 9+: Incluido con Node.js. Verifica con npm --version.
• Ollama instalado: Descarga desde ollama.com/download (macOS, Windows o Linux).
• Conexión a internet activa: Requerida para modelos en la nube como kimi-k2.5:cloud.
• Cuenta Ollama (opcional para nube): Para acceder a modelos en la nube y planes Pro/Max de Ollama.
• Clave API alternativa: Si prefieres usar Claude, GPT u otro proveedor directamente sin Ollama como intermediario.

PARTE 1 — Para novatos: instalación completa con Ollama

Paso 1: Instalar Ollama

Ollama es el punto de entrada más simple para lanzar PI, ya que gestiona automáticamente la instalación, el proveedor y los plugins web. Descárgalo desde ollama.com/download y sigue el instalador para tu sistema operativo. Verifica la instalación con:

ollama --version

Si el comando no se reconoce, cierra y vuelve a abrir la terminal. En Linux, ejecuta adicionalmente:

export PATH=$PATH:/usr/local/bin && source ~/.bashrc

Paso 2: Lanzar PI con Kimi-K2.5 desde Ollama

Este es el comando central de la guía. Un solo comando descarga e instala PI, configura Ollama como proveedor, habilita herramientas web y soporte multimodal, y lanza la interfaz interactiva (Ollama, 2026):

ollama launch pi --model kimi-k2.5:cloud

Durante el primer lanzamiento, el proceso automático ejecuta estos pasos en orden:

1. Verifica si PI está instalado; si no, lo instala vía npm sin intervención manual.
2. Muestra un aviso de permisos de herramientas; escribe y para aceptar.
3. Configura Ollama como proveedor principal con kimi-k2.5:cloud como modelo activo.
4. Instala automáticamente los plugins de búsqueda web, fetch y soporte de imágenes.
5. Abre la interfaz TUI lista para recibir tareas.

Paso 3: Instalación alternativa directa con npm (sin Ollama)

Si prefieres conectar PI directamente a otro proveedor (Claude, GPT, Gemini, etc.) sin pasar por Ollama, instala PI de forma global con npm:

npm install -g @mariozechner/pi-coding-agent

Luego configura la clave API del proveedor que prefieras antes de lanzar PI:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# OpenAI (GPT)
export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# Google (Gemini)
export GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxx

Para que la clave persista entre sesiones sin necesidad de exportarla cada vez, agrégala al archivo de perfil de tu terminal (~/.bashrc, ~/.zshrc o ~/.profile) y ejecuta source ~/.bashrc. Después lanza PI con:

pi

PARTE 2 — Para expertos: integrar con instalaciones existentes

¿Cómo cambiar de modelo en PI ya instalado?

Si ya tienes PI corriendo con otro modelo o proveedor, hay dos métodos para migrar sin perder configuración:

Opción A — Desde dentro de PI (sin reiniciar):

/model

Esto abre el selector de modelos. Navega con las flechas del teclado, elige ollama/kimi-k2.5:cloud y presiona Enter. El cambio es instantáneo.

Opción B — Desde la terminal con proveedor y modelo explícitos:

pi --provider ollama --model kimi-k2.5:cloud

Verificar modelo y estado activo:

/settings

Los cuatro modos de operación de PI

PI opera en cuatro modos diseñados para cubrir desde el uso diario hasta la integración en pipelines automatizados (MOGE, 2026):

1. Modo interactivo (TUI): Por defecto. Abre la interfaz completa de terminal con historial, soporte de imágenes y navegación de sesiones.

   pi                         # Nueva sesión
   pi -c                      # Continuar sesión más reciente
   pi -r                      # Elegir sesión de la lista
   pi "Analiza src/main.ts"   # Inicia con mensaje específico
   pi --session nombre        # Continuar sesión con nombre

2. Modo print (no interactivo): Responde una sola vez y sale. Ideal para scripts o consultas rápidas.

   pi -p "Resume el README.md"
   cat error.log | pi -p "Identifica los errores críticos"

3. Modo JSON: Devuelve la respuesta en JSON estructurado, procesable con herramientas como jq.

   pi --mode json "Lista funciones sin documentar en src/" | jq '.content'

4. Modo RPC: Controla PI desde otro proceso externo vía stdin/stdout. Diseñado para integrar PI como motor de agente en aplicaciones propias (MOGE, 2026). Es el modo que usa OpenClaw internamente para orquestar PI como backend.

Las cuatro herramientas nativas de PI

El núcleo de PI provee exactamente cuatro herramientas que el modelo utiliza para interactuar con el sistema. Su minimalismo es intencional: ninguna herramienta innecesaria contamina el contexto ni introduce comportamiento no deseado (MOGE, 2026):

• read — Lee el contenido de archivos. Ejemplo: “Lee src/auth.ts y explica el flujo de autenticación”.
• write — Crea o sobreescribe archivos. Ejemplo: “Crea un archivo validators.ts con funciones de validación de email y teléfono”.
• edit — Edita fragmentos exactos de código sin reescribir el archivo completo. Más preciso y seguro para cambios puntuales.
• bash — Ejecuta comandos de shell. Ejemplo: “Corre los tests y muéstrame cuáles fallan con su stack trace”.

Para restringir las herramientas disponibles (modo solo lectura, por ejemplo), usa el flag --tools:

pi --tools read,grep,find,ls "Audita la seguridad de este proyecto sin modificar nada"

Controles del modo interactivo

• Enter — Enviar el mensaje al modelo.
• Shift + Enter — Salto de línea sin enviar (mensajes multilinea).
• Ctrl + V — Pegar imagen directamente en el chat.
• @ + nombre de archivo — Referenciar un archivo del proyecto en el mensaje.
• / — Ver la lista completa de comandos disponibles.
• Ctrl + C o Escape — Cancelar operación en curso o salir del modo actual.

Comandos internos esenciales:

• /login — Autenticarse con un proveedor de IA de forma interactiva.
• /model (o Ctrl + L) — Cambiar modelo en tiempo real sin reiniciar la sesión.
• /settings — Configuración general de PI.
• /tree — Ver historial de la sesión en estructura tipo árbol (similar a git log).
• /compact — Resumir el contexto cuando el historial excede la ventana del modelo.
• /quit — Salir de PI.

Extensiones avanzadas: subagentes y autoresearch

¿Cómo usar subagentes para tareas complejas?

Para tareas que requieren coordinar múltiples agentes en paralelo —como investigación profunda, refactorización de bases de código grandes o análisis multiarchivo simultáneo—, PI dispone de la extensión pi-subagents. Permite que el agente principal instancie y coordine agentes hijos especializados, cada uno trabajando en una subtarea distinta (Ollama, 2026). Instálala con un solo comando:

pi install npm:pi-subagents

Una vez instalada, PI puede gestionar automáticamente múltiples agentes cuando detecta que la tarea lo requiere, o puedes invocarla explícitamente en tus prompts indicando el número de agentes paralelos deseados.

¿Qué es pi-autoresearch y cómo funciona?

Inspirada en el trabajo de Andrej Karpathy, la extensión pi-autoresearch implementa bucles de optimización autónomos: el agente propone un cambio, lo ejecuta, evalúa si mejoró el resultado y, si fue así, lo conserva; si no, lo revierte con git reset y repite el ciclo (DataCamp, 2026). El CEO de Shopify, Tobi Lütke, corrió un bucle similar sobre Liquid —el motor de plantillas que corre en cada tienda Shopify, un código con 20 años de antigüedad— y obtuvo 53% más velocidad de renderizado con 61% menos uso de memoria, con 974 tests unitarios pasando sin excepción (Saladi, 2026). Instala la extensión con:

pi install https://github.com/davebcn87/pi-autoresearch

Para iniciar un bucle de optimización una vez instalada:

1. Lanza PI con Ollama: ollama launch pi --model kimi-k2.5:cloud
2. Dentro de la interfaz, activa el bucle con el comando de la extensión:

/autoresearch optimize test runtime and monitor correctness

El agente comenzará a ejecutar ciclos de mejora autónomamente. Cada ciclo sigue este proceso interno:

1. Lee el archivo program.md con la dirección de investigación definida.
2. Propone y aplica un cambio al código fuente.
3. Ejecuta los tests durante exactamente 5 minutos.
4. Evalúa el resultado: si mejoró, el commit se conserva; si no, git reset lo revierte.
5. El ciclo se repite automáticamente hasta que se detenga manualmente (DataCamp, 2026).

Archivos de contexto: instrucciones del proyecto

PI carga automáticamente archivos de instrucciones al iniciar una sesión, evitando repetir contexto en cada mensaje. Esto resulta especialmente valioso en equipos que comparten repositorios con convenciones específicas (AICodeKing, 2026):

• AGENTS.md o CLAUDE.md — Buscados en el directorio actual y en todos los directorios padre.
• ~/.pi/agent/AGENTS.md — Instrucciones globales que aplican a todas las sesiones en cualquier proyecto.
• SYSTEM.md — Reemplaza completamente el system prompt base de PI para control total del comportamiento del agente (MOGE, 2026).

Ejemplo funcional para un proyecto TypeScript:

# Instrucciones del Proyecto

- Usa TypeScript 5.4 y Node.js 20 estrictamente.
- No modificar archivos en /dist directamente.
- Todos los tests deben pasar antes de cualquier commit.
- Usa camelCase para variables, PascalCase para clases e interfaces.
- El idioma del código y los comentarios es inglés.
- Nunca uses console.log en producción; usa el logger de Winston.

Sistema de extensibilidad: skills, plantillas y temas

PI dispone de cuatro capas de personalización que se instalan en ~/.pi/agent/ y pueden distribuirse como paquetes en npm o Git (MOGE, 2026):

• Skills (skills/): Capacidades cargadas bajo demanda para no saturar el contexto. Cada skill es una carpeta con un archivo skill.md con instrucciones y flujos de trabajo. Se invocan con /skill:nombre.
• Plantillas de prompts (prompts/): Prompts reutilizables invocables como comandos directos (/nombre-template). Por ejemplo, una plantilla code-review.md se usa con /code-review.
• Extensiones TypeScript (extensions/): Módulos que se enganchan en más de 25 puntos del ciclo de vida del agente: herramientas custom, bloqueo de comandos peligrosos, subagentes, UI personalizada, hooks de eventos (MOGE, 2026).
• Temas (themes/): Paletas de color personalizadas para la interfaz de terminal.

Sistema de paquetes de la comunidad

# Instalar desde npm
pi install npm:@usuario/nombre-paquete

# Instalar desde repositorio Git
pi install https://github.com/usuario/repositorio

# Ver paquetes instalados
pi list

# Actualizar todos los paquetes
pi update

Modelos locales vs. nube: cuándo usar cada uno

PI funciona con ambos paradigmas según los recursos disponibles y la complejidad de la tarea. Para tareas de exploración, revisión de código ligera o desarrollo en máquinas con GPU dedicada, los modelos locales vía Ollama ofrecen privacidad total y cero costo por token (Ollama, 2026). Para tareas más exigentes como autoresearch, refactorización masiva o uso de Kimi-K2.5 completo (que requiere más de 240 GB de RAM para rendimiento óptimo), la nube de Ollama es la opción práctica (Unsloth, 2026). Los planes Pro y Max de Ollama amplían el acceso a modelos grandes en la nube; consulta los detalles en ollama.com/pricing.

¿Cómo resolver los errores más frecuentes?

• command not found: pi — Reinicia la terminal. En Linux/macOS ejecuta: export PATH=$PATH:$(npm bin -g) && source ~/.bashrc.
• command not found: ollama — El servidor de Ollama no está en el PATH. En Linux: export PATH=$PATH:/usr/local/bin && source ~/.bashrc.
• connection refused 127.0.0.1:11434 — Ollama no está corriendo. Ejecuta ollama serve en una terminal separada y déjala abierta.
• PI no instala vía Ollama — Verifica que Node.js 18+ esté instalado con node --version. Si la versión es inferior, actualiza desde nodejs.org.
• kimi-k2.5:cloud no responde — Verifica conexión a internet. Ejecuta ollama ps para confirmar que el modelo está activo. Si no aparece, vuelve a lanzar con ollama launch pi --model kimi-k2.5:cloud.
• Contexto demasiado largo — Usa /compact dentro de PI para resumir el historial y liberar espacio en la ventana de contexto del modelo.
• Cambio de modelo no persiste entre sesiones — Agrega --provider ollama --model kimi-k2.5:cloud directamente al alias de lanzamiento en tu .bashrc: alias pi='pi --provider ollama --model kimi-k2.5:cloud'.

Flujo de trabajo completo: de cero a autoresearch en 5 pasos

1. Instalar y lanzar PI con Ollama:

   ollama launch pi --model kimi-k2.5:cloud

2. Crear el archivo de contexto del proyecto:

   echo "# Proyecto\n- TypeScript 5.4, tests con Vitest\n- No modificar /dist" > AGENTS.md

3. Instalar subagentes para tareas paralelas:

   pi install npm:pi-subagents

4. Instalar autoresearch para bucles de optimización:

   pi install https://github.com/davebcn87/pi-autoresearch

5. Iniciar un bucle de optimización autónomo:

   /autoresearch optimize test runtime and monitor correctness

   PI ejecutará ciclos continuos de mejora, conservando solo los cambios verificados, hasta que decidas detenerlo.