Paperclip Starter Guide: crea tu primera empresa de AI Agents

Si solo tienes un AI Coding Agent, el flujo de trabajo es bastante sencillo:

Usuario
↓
Claude Code / Codex
↓
Completa la tarea

Pero cuando empiezas a tener varios agentes, el problema deja de ser únicamente si “el modelo puede escribir código”.

Imagina que ahora tienes un CEO, un Developer, un Researcher y un Designer:

              CEO
          ┌────┼────┐
          ↓    ↓    ↓
     Developer Research Designer

¿Quién se encarga de cada cosa? ¿Quién asigna las tareas? ¿Cuándo trabaja cada Agent? ¿A quién se entrega el trabajo terminado? ¿Cuánto gasta cada Agent? ¿Y dónde se puede pausar o volver a ejecutar un Agent cuando algo sale mal?

Eso es precisamente lo que intenta resolver Paperclip.

Puede entenderse como el Control Plane de un equipo de AI Agents: se encarga de Companies, Goals, Agents, Org Chart, Tasks, Budgets y Heartbeats, mientras que la ejecución real sigue dependiendo de runtimes externos como Claude Code, Codex o Cursor. La documentación oficial distingue explícitamente Paperclip de un Agent Framework, un Chatbot o un Workflow Builder.

Primero entiende los conceptos fundamentales de Paperclip

Cuando lo utilices por primera vez, no tengas prisa por crear diez Agents. Empieza por entender algunos objetos básicos.

Company es el nivel superior. Puedes entenderla como un equipo de AI. Tiene sus propios objetivos, Agents, proyectos, tareas y presupuesto.

Agent es el “empleado” de la empresa. Sin embargo, no es simplemente un modelo: combina un rol, relaciones dentro de la organización, un Adapter, un directorio de trabajo, un presupuesto y otras configuraciones.

Goal define qué quiere conseguir la empresa. Por ejemplo:

Build and launch a small AI tools website.

Task / Issue representa el trabajo concreto que debe realizarse para alcanzar ese objetivo.

Org Chart define quién reporta a quién, por ejemplo:

CEO
├── Developer
└── Researcher

Por su parte, Adapter es el puente entre Paperclip y el runtime de AI que realmente ejecuta el trabajo. Paperclip no sustituye a Claude Code o Codex, sino que los inicia y gestiona mediante Adapters. La documentación oficial actual incluye Adapters como claude_local, codex_local, opencode_local y Cursor.

Por último está Heartbeat: un Agent no tiene por qué estar funcionando permanentemente. Se despierta cuando corresponde, ejecuta una ronda de trabajo y termina. El sistema admite activaciones programadas, asignación de tareas, ejecución manual y automatizaciones.

Instalar Paperclip

El Quickstart oficial recomienda actualmente utilizar directamente:

npx paperclipai onboard --yes

Este comando realiza la configuración inicial y pone en marcha Paperclip. Actualmente se requiere Node.js 24.11 o superior. La instalación local utiliza PostgreSQL embebido por defecto, por lo que no necesitas instalar una base de datos independiente para la primera prueba.

Para comprobar tu versión de Node.js:

node --version

Debería mostrar v24.11.0 o una versión superior.

Una vez completado el primer arranque, Paperclip puede abrirse normalmente en:

http://localhost:3100

Para volver a iniciar una instancia que ya está configurada, puedes utilizar:

npx paperclipai run

La documentación oficial recomienda que, si realizaste la instalación inicial mediante npx, continúes utilizando npx paperclipai. pnpm paperclipai está orientado principalmente al desarrollo local a partir del código fuente clonado.

Crear tu primera Company

Una vez dentro de Paperclip, el primer paso no debería ser crear muchos Agents, sino establecer una Company mínima.

Por ejemplo:

Company:
AI Content Studio

Goal:
Build a small AI tools website.

El Goal es importante.

No es simplemente una nota descriptiva, sino el objetivo de nivel superior alrededor del cual se organiza el trabajo. Las tareas de Paperclip pueden asociarse con proyectos y Goals, de modo que un Agent no solo recibe información sobre “qué tengo que hacer”, sino también sobre el objetivo que hay detrás de esa tarea.

Para una primera prueba, basta con utilizar un objetivo sencillo y concreto.

Crear el primer CEO Agent

El siguiente paso es crear el CEO.

Puedes entenderlo de esta forma:

Company
   ↓
  CEO
   ↓
Planificar / Crear tareas / Delegar trabajo

El CEO no tiene por qué ser un modelo especial. En esencia, sigue siendo un Agent que asume una función de coordinación dentro de la organización.

Después de crear el Agent, debes seleccionar un Adapter.

Por ejemplo, si utilizas Claude Code:

Paperclip
   ↓
claude_local
   ↓
Claude Code
   ↓
Ejecución real de tareas

O si utilizas Codex:

Paperclip
   ↓
codex_local
   ↓
Codex CLI
   ↓
Ejecución real de tareas

La documentación oficial de Adapters muestra actualmente Claude Code y Codex entre los Adapters locales disponibles. Los respectivos CLI deben estar instalados y autenticados previamente.

Este punto es fundamental:

Paperclip gestiona los Agents, pero no proporciona por sí mismo el Agent que realiza el trabajo.

Configurar el Heartbeat del CEO

Ahora ya tienes un CEO, pero el hecho de que exista dentro de Paperclip no significa que vaya a trabajar continuamente.

Debes configurar su Heartbeat.

Para empezar, puedes utilizar una frecuencia relativamente conservadora, por ejemplo:

Every 1 hour

Una ejecución de Heartbeat puede entenderse aproximadamente así:

Wake Up
↓
Leer las tareas y el contexto actual
↓
Iniciar el Adapter
↓
El Agent ejecuta el trabajo
↓
Guardar resultados / estado / costes
↓
Finalizar esta ejecución

El sistema de ejecución oficial utiliza este modelo de heartbeat execution en lugar de mantener al Agent ocupando permanentemente un proceso. La asignación de una tarea también puede provocar que el Agent se active.

Para la primera prueba, no configures un Heartbeat cada pocos minutos. Cada Heartbeat puede activar un runtime de AI real, lo que implica llamadas al modelo y posibles costes. Paperclip ofrece controles presupuestarios, pero no convierte las llamadas a los modelos en gratuitas.

Hacer que el CEO empiece a organizar el trabajo

Ahora ya tienes:

Company
↓
Goal
↓
CEO
↓
Adapter
↓
Heartbeat

El siguiente paso es hacer que el CEO trabaje alrededor del objetivo.

Por ejemplo, si el objetivo es:

Build a small AI tools website.

El CEO podría dividirlo en:

AI Tools Website
│
├── Research competitors
├── Design site structure
├── Build homepage
├── Build article system
└── Prepare deployment

En la primera prueba, simplemente observa cómo el CEO crea y gestiona las tareas antes de añadir muchos Agents.

Aquí empieza a verse el propósito de Paperclip: ya no tienes que decirle personalmente a la AI qué debe hacer después de cada paso. Primero defines un objetivo para la organización y después permites que los Agents trabajen según sus responsabilidades.

Añadir un segundo Agent

Cuando el CEO funcione correctamente, añade un Developer.

La estructura quedaría así:

CEO
└── Developer

Puedes asignarle una responsabilidad clara:

Role:
Software Engineer

Después, permite que el CEO asigne una tarea concreta de desarrollo al Developer.

El flujo completo sería aproximadamente:

Company Goal
      ↓
     CEO
      ↓
Crear Task
      ↓
 Developer
      ↓
Claude Code / Codex
      ↓
Completar el trabajo

Después puedes añadir un Researcher:

       CEO
      /   \
Developer Researcher

Con esto ya tienes una Agent Company mínima.

No hagas demasiado grande la primera tarea

Para la primera prueba conviene elegir una tarea fácil de verificar.

Por ejemplo:

Goal:
Create a simple landing page for an AI tools website.

CEO:
Break the work into tasks.

Researcher:
Analyze several competing AI tool websites.

Developer:
Build the landing page.

Así puedes observar todo el flujo:

Goal
↓
CEO
↓
Task
↓
Agent
↓
Adapter
↓
Ejecución real
↓
Resultado

Si en la primera prueba haces que cinco o seis Agents “gestionen automáticamente una empresa”, será mucho más difícil determinar si un problema procede del Goal, Task, Agent, Adapter, Heartbeat o del propio modelo.

Por qué conviene prestar atención al Budget desde el principio

Cuando pasas de uno a diez Agents, la estructura de costes cambia rápidamente:

Múltiples Agents
×
Múltiples Heartbeats
×
Llamadas a modelos
=
Costes continuos

Paperclip permite realizar un seguimiento de los costes y establecer presupuestos y límites de ejecución. Cuando se alcanza un límite presupuestario, las ejecuciones correspondientes pueden pausarse.

Por eso, para el primer experimento es recomendable utilizar solo 1 CEO + 1 o 2 Agents especializados.

Especialmente, evita configurar Heartbeats extremadamente frecuentes simplemente para conseguir una mayor “autonomía”. Que un Agent tenga más autonomía no significa que deba despertarse con mayor frecuencia.

Problemas más habituales para principiantes

He creado el Agent, pero ¿por qué no trabaja?

Comprueba primero que el Adapter esté correctamente configurado y que el CLI correspondiente esté instalado y autenticado. Sin un Adapter, el Agent es básicamente un registro dentro de la estructura organizativa de Paperclip y no puede ejecutar trabajo real.

¿Por qué el Agent se ejecuta repetidamente?

Comprueba el Heartbeat y las condiciones que activan las tareas. El sistema de ejecución de Paperclip puede despertar Agents mediante eventos programados, asignaciones de tareas y otros triggers.

¿Por qué los costes están aumentando tan rápido?

Comprueba primero la frecuencia de los Heartbeats y el número de Agents. Después revisa el presupuesto asignado a cada Agent.

¿Es obligatorio tener un CEO?

Para una primera prueba, el CEO es una buena forma de entender el modelo organizativo de Paperclip. Sin embargo, el diseño de una organización real no debería copiar mecánicamente la jerarquía de una empresa tradicional.

¿Paperclip proporciona los modelos?

No. Paperclip se centra principalmente en el Control Plane y la orquestación de Agents. La ejecución real depende del Runtime / Adapter que hayas configurado.

Una vez que funcione, amplía la organización poco a poco

Después de conseguir una primera ejecución correcta, puedes ampliar gradualmente la estructura:

                 CEO
              /   |   \
            CTO  Research  Marketing
           /  \
     Frontend Backend

Después puedes experimentar con diferentes Adapters, modelos, presupuestos y flujos de trabajo más complejos.

Pero no conviertas el número de Agents en un objetivo en sí mismo.

Lo realmente importante de Paperclip es esta capa:

Claude Code / Codex / Other Agents
                ↓
             Adapters
                ↓
             Paperclip
                ↓
      Company / Goals / Tasks
       /        |        \
   Agents    Budgets   Heartbeats

Los Agents hacen el trabajo; Paperclip organiza cómo trabajan esos Agents.

Si solo utilizas ocasionalmente un único Claude Code o Codex, Paperclip probablemente añada una complejidad innecesaria. Cuando empiezas a gestionar varios Agents con diferentes responsabilidades, distintos Runtimes y ejecución prolongada, su enfoque de Control Plane empieza a resultar mucho más relevante.

Al utilizarlo por primera vez, lo más importante no es memorizar un botón o un comando concreto, sino entender esta idea:

Paperclip no intenta hacer que una AI individual sea más inteligente, sino permitir que varios AI Agents trabajen alrededor de objetivos comunes mediante organización, división de responsabilidades, activación, supervisión y control de costes.

Repositorio oficial de Paperclip en GitHub · Documentación oficial de Paperclip