Construir una fuerza laboral con Paperclip: curso acelerado de 90 minutos

6 escenarios, de cero a una fuerza laboral de IA gestionada

Paperclip es la empresa frente al empleado que representa OpenClaw. Donde el curso acelerado de OpenClaw te dio un Worker de IA que vive en tu portátil, este te da la empresa que contrata, gobierna y audita una flota de ellos. Un Worker es una función; una fuerza laboral es un organigrama de Workers que operan contra presupuestos, bajo aprobaciones y dejando una pista de auditoría. Paperclip es la empresa alrededor del Worker.

Paperclip es joven y avanza rápido: decenas de miles de estrellas en GitHub para mediados de 2026, licencia MIT, autohospedado y ejecución completa en tu portátil con un solo comando (sin cuenta, sin tarjeta de crédito, sin configuración en la nube). La misma ausencia de fricción que OpenClaw consiguió para el Worker, Paperclip la consigue para la empresa que lo rodea.

Al final de estos noventa minutos tendrás una empresa real nativa de IA ejecutándose en tu máquina:

• una entidad de empresa con un propósito definido,
• un Worker contratado contra un adaptador y listo para recibir trabajo,
• un issue entrante asignado y llevado hasta completarse por un Worker local sin clave,
• una aprobación presentada ante ti (la junta) y decidida con un registro auditado permanente,
• un Worker real respaldado por un LLM añadido para que un presupuesto por fin tenga datos que aplicar, y
• una sola consulta SQL que reconstruye todo lo ocurrido en milisegundos.

No es una demo que olvidarás para el viernes; es un sustrato que tocarás mañana.

---

Cómo funciona este curso acelerado. Descargas una carpeta pequeña, se la entregas a tu agente de codificación (Claude Code u OpenCode) y recorres seis escenarios. El agente lee la carpeta, instala Paperclip, configura tu primera empresa, contrata tu primer Worker, asigna tu primer issue y presenta la primera aprobación. Después sustituye el Worker stub sin clave por un Worker LLM real para que el presupuesto tenga algo que medir, y responde una pregunta de auditoría de nivel CFO consultando el registro de actividad. Tú diriges; el agente trabaja; Paperclip se convierte en el plano de gestión por el que pasa tu fuerza laboral.

Ruta de lectura · requisitos previos · la versión detallada (haz clic para expandir)

Ruta de lectura (seis escenarios + un hábito mensual):

1. Levanta Paperclip y define tu empresa. Onboarding, dashboard activo, una empresa configurada. ~15 min.
2. Contrata tu primer Worker. Un Worker local sin clave (worker-stub.py, incluido en tu descarga) registrado en el adaptador http, listo para recibir heartbeats. ~15 min.
3. Envía a la empresa su primer issue real. Se crea un issue, se asigna al Worker en el momento de creación, se recoge en el siguiente heartbeat y se resuelve. ~15 min.
4. Presenta una aprobación para una acción riesgosa. Un reembolso de $750 necesita la aprobación de la junta; presentas la solicitud, la decides y lees el registro auditado. ~15 min.
5. Sustituye por un Worker LLM real; dale fuerza al presupuesto. El stub sin clave no hace trabajo facturable, así que el presupuesto nunca se mueve. Añade un Worker real respaldado por Gemini y observa cómo se acumula el gasto. ~15 min.
6. Consulta la pista de auditoría como un CFO. Una consulta SQL, toda la historia de la empresa, en milisegundos. ~10 min.
7. (Una vez al mes, no hoy) Ejecuta la auditoría de la fuerza laboral. ~10 min cuando llegue el momento.

Cada escenario termina en un resultado ejecutable. Si noventa minutos en una sola sesión es demasiado, hazlos como sesiones separadas; todo persiste entre ellas. Los escenarios 3 a 6 se construyen sobre la empresa y el Worker de 1 y 2.

Requisitos previos (la página asume esto):

1. Claude Code u OpenCode instalado. Cualquiera de los dos funciona. Si no tienes ninguno, haz primero el curso acelerado de codificación agéntica.
2. Node.js 20 o posterior. Ejecuta node --version en una terminal. Por debajo de v20.0.0, instala la versión LTS desde nodejs.org/en/download; tu agente de codificación te guiará si se lo pides.
3. Python 3. Ejecuta python3 --version. El Worker que contratas en el escenario 2 es un pequeño archivo Python (worker-stub.py, de unas 120 líneas) incluido en tu descarga y usa solo la biblioteca estándar: no hay nada que pip install. macOS y la mayoría de Linux ya incluyen Python 3; en Windows, tu agente de codificación te ayudará a instalarlo.
4. Una clave gratuita de API de Gemini, solo para el escenario 5. Los escenarios 1 a 4 y el escenario 6 se ejecutan sin ninguna clave de API. El escenario 5 sustituye el stub sin clave por un Worker LLM real, y ese necesita una clave. El nivel gratuito de Google basta; es la misma clave que usa el curso acelerado de OpenClaw. Consigue una en aistudio.google.com antes de empezar, o cuando llegues al escenario 5.
5. Has hecho uno de los cursos acelerados previos sobre Workers de IA, idealmente OpenClaw o Digital FTE. El objetivo de Paperclip es gestionar una fuerza laboral de Workers; conviene saber qué es un Worker antes de empezar a contratarlos.

¿Quieres la versión pausada? Dos cursos acelerados complementarios rodean a este en la pista. De Digital FTE a Worker de producción envuelve un solo Worker en la envoltura de durabilidad de Inngest: el paso justo antes de una fuerza laboral. De fuerza laboral fija a dinámica convierte la contratación en una capacidad invocable: el paso justo después. Esta página más el brief AGENTS.md cubren el plano de gestión de extremo a extremo; esos dos se superponen encima, no lo reemplazan.

---

El patrón de colaboración

Tres actores comparten esta página: tú, tu agente de codificación y Paperclip. Pegas prompts y tomas las decisiones que solo un humano puede tomar. Tu agente de codificación ejecuta la CLI y la API de Paperclip, observa los logs y se recupera de fallas. Paperclip es el plano de gestión: contiene la empresa, contrata los Workers, les lleva trabajo en un heartbeat y registra cada acción.

Cada escenario usa el mismo ritmo de cinco pasos:

1. Pegas una frase en tu agente de codificación. Es un brief, no un script. Describes el resultado que quieres; no enumeras pasos.
2. Tu agente consulta AGENTS.md (ya está en su contexto: CLAUDE.md en la carpeta lo importa automáticamente al iniciar la sesión, así que no hay paso de descarga) y propone un plan. Nombra los comandos que pretende ejecutar y marca cualquier punto de decisión. Pregunta antes del primer comando destructivo.
3. Apruebas y observas. El agente ejecuta comandos de instalación, llama a la API, observa el log del servidor y te muestra lo que ve. Cuando encuentra una falla conocida, reconoce el patrón desde el brief y aplica la corrección documentada.
4. Tu agente se detiene en el punto de intervención. Algunos movimientos solo puedes hacerlos tú: abrir la URL del dashboard, decidir si se debe conceder un reembolso de $750, exportar una clave de API. El agente nombra el punto de intervención y espera.
5. Terminas cuando ocurre algo observable. Aparece una fila nueva en el registro de actividad. Un issue pasa a done. Una consulta SQL devuelve la historia esperada. Cada escenario te dice qué debes observar.

Eso es todo. El agente hace lo que un agente hace bien: instalar, configurar, depurar, consultar, recuperarse. Tú haces lo que solo tú puedes hacer: decidir, aprobar y actuar sobre lo que está ligado a tus cuentas. Este ritmo (describir el objetivo, obtener el plan, aprobar, ejecutar con verificación en cada paso) es el mismo patrón de prompting que se enseña en el curso acelerado de prompting de IA en 2026. Cada escenario de abajo usa dos prompts breves para pegar en lugar de una pared de instrucciones, para que experimentes el ritmo en vez de solo leer sobre él.

Un movimiento de recuperación para todo el curso acelerado

Si algo se tuerce en cualquier momento, no necesitas conocer comandos de CLI ni códigos de error. Pega esto a tu agente:

Algo no funcionó. Ejecuta paperclipai doctor, luego lee el log más reciente del servidor de Paperclip, dime en lenguaje claro qué ves y propón una corrección que pueda aprobar.

Tu agente ejecuta el diagnóstico, lee el log, nombra lo que ve y propone la corrección. Tú apruebas. Ese es el bucle de recuperación para cada escenario de esta página.

Si un escenario tarda demasiado

Cada escenario tiene un tiempo presupuestado (mostrado en el H2). Si superas 2x ese presupuesto (por ejemplo, más de 30 minutos en un escenario de 15 minutos), trae de vuelta a tu agente y pega: "¿Qué nos está bloqueando, en una frase? Volvamos a planificar desde ahí." Pasarse del presupuesto normalmente significa que el agente está improvisando; volver a anclarlo al plan lo corrige.

La carpeta que descargarás tiene exactamente tres archivos: AGENTS.md (una referencia operativa compacta para cualquier agente de codificación que trabaje con Paperclip), CLAUDE.md (una línea, @AGENTS.md, que indica a Claude Code que importe el brief automáticamente) y worker-stub.py (el Worker local sin clave que contratas en el escenario 2). Ese es todo el entorno.

Descargar paperclip-crash-course.zip

Descomprime en cualquier lugar. Abre una terminal en la carpeta descomprimida. Inicia tu agente de codificación:

cd paperclip-crash-course
claude

Tu agente ya tiene cargado el brief. Recorremos seis escenarios, uno por uno; cada uno termina en un resultado ejecutable antes de pasar al siguiente. Este brief asume un agente de codificación capaz (Claude Code, u OpenCode ejecutando un modelo frontera actual). Los modelos más antiguos o pequeños tenderán a desviarse, sobre todo en el JSON exacto del cuerpo para crear el Worker en el escenario 2 y en el SQL del escenario 6. Si el primer plan de tu agente en el escenario 1 se ve vago o genérico en vez de específico para tu máquina, esa es la señal para cambiar a uno más fuerte antes de seguir.

---

Antes del escenario 1: confirma que tu agente tenga cargado el brief (~30 s)

Una sola frase pegada te dice si CLAUDE.md hizo su trabajo y llevó AGENTS.md al contexto de tu agente:

¿Qué puedes hacer por Paperclip?

Si la respuesta nombra trabajo específico de Paperclip (la prueba previa a la instalación, la forma de empresa y Worker, el contrato de heartbeat, la asignación de issues al crear, el payload de aprobación, la realidad del presupuesto, las consultas del registro de actividad, el hábito de auditoría mensual), estás cargado y listo para el escenario 1. Si suena a charla genérica sobre capacidades de IA sin detalles específicos de Paperclip, la importación no se disparó: cierra el agente, confirma que estás dentro de la carpeta descomprimida paperclip-crash-course/ y relanza.

Qué hay realmente en AGENTS.md (el archivo que tu agente está leyendo ahora)

Nunca necesitarás leer este archivo tú mismo; ese es el punto. Pero conocer su forma te ayuda a hacer mejores preguntas ("explícame la sección de aprobaciones" funciona porque la sección existe). El brief cubre, en orden:

PART 1 :: PRINCIPLES (apply everywhere)
  Versions this brief was verified against
  Source of truth, in order         ← live docs > this brief > the running install
  Critical: discover before you act  ← table of intent → where to confirm
  Working pattern (every task)       ← read → propose → ask → execute → verify
  Past tense is for completed actions only
  Trust progression                  ← ask each, then blanket; re-acquire on anomaly
  Safety rails (non-negotiable)
  Secrets discipline
  Sourcing claims that exist only in this brief

PART 2 :: OPERATIONS (verified against a live install)
  Install and onboard            ← the pre-install probe + the onboard flow
  Configure                      ← second instance, keeping the server alive
  Companies                      ← create, goals, projects
  Agents (Workers) and adapters  ← the real adapter list + the verified create body
  The heartbeat contract         ← what the http adapter actually POSTs
  Issues and assignment          ← no routing engine; assign at create time
  Approvals                      ← the payload + why it's a decision record
  Budgets                        ← why they only move for LLM Workers
  Audit trail                    ← activity_log + the real connection string
  Diagnose and recover           ← the most common failures
  When you don't know what to do ← three-layer fallback

Si una sección concreta de AGENTS.md parece relevante más adelante, puedes pedir a tu agente que te la explique antes de actuar (por ejemplo, "explícame la sección Approvals de AGENTS.md antes de presentar esa solicitud"). El brief fue escrito para que el agente pueda autodirigirse desde él.

Nota sobre la ruta de laboratorio: ejecuta todo el pipeline sin clave

El Worker que contratarás en el escenario 2 es worker-stub.py, un Worker local sin clave incluido en tu descarga. Se ejecuta en el adaptador http de Paperclip: en cada heartbeat, Paperclip envía por POST el issue completo al stub, y el stub publica una disposición de vuelta. Sin LLM, sin clave de API, sin segunda herramienta. Ejecutas todo el plano de gestión (heartbeats, asignación, aprobaciones, auditoría) de extremo a extremo con lo que ya tienes, a través de los escenarios 1 a 4 y el escenario 6. Luego, en el escenario 5, añades una cosa, una clave gratuita de Gemini, por una razón deliberada: el stub sin clave no hace trabajo facturable, así que un presupuesto no tiene nada contra lo cual medirse. El Worker LLM real es lo que da al presupuesto algo que aplicar. La forma del pipeline es idéntica en ambos casos; el stub sin clave solo produce una disposición de stub en vez de un borrador de respuesta.

---

Escenario 1: levanta Paperclip y define tu empresa (~15 min)

El objetivo: Paperclip ejecutándose en tu portátil, una empresa configurada ("Acme Customer Support" o el nombre que elijas), y el dashboard accesible en tu navegador. Dos prompts: pedir el plan, aprobar y ejecutar.

1a. Haz el onboarding y verifica la instalación

Primer prompt: describe lo que quieres y pide el plan.

Quiero poner Paperclip en marcha en mi portátil y recorrer una primera empresa llamada Acme Customer Support. Antes de tocar nada, ejecuta la prueba previa a la instalación desde tu brief y explícame tu plan en lenguaje claro: qué revisaste, qué cambiarás y dónde necesitarás que intervenga.

Tu agente lee AGENTS.md, ejecuta la prueba previa a la instalación (versión de Node, instalaciones previas, disponibilidad de puertos, directorio de datos previo, otros procesos de Paperclip en ejecución) y propone un plan. Marcará un lugar donde probablemente te necesite: si hay algún estado obsoleto (una instalación previa de paperclipai, un proceso ocupando el puerto predeterminado), se detiene para pedir tu decisión antes de tocarlo. Lee el plan. Si algo no encaja, cuestiona. Pregunta "¿por qué haces eso?" y el agente explicará o ajustará.

Segundo prompt: aprueba y deja que se ejecute.

El plan se ve bien. Avanza paso a paso y dime qué ves en cada paso. Pausa antes de cualquier comando destructivo. Cuando termine el onboarding, nombra la URL del dashboard para que pueda confirmar que la veo en mi navegador; en algunas configuraciones se abre automáticamente.

El agente ejecuta el comando de onboarding desde el brief, observa su salida y captura los valores operativos que imprime el script: el host de la API, la URL del dashboard, la ruta del directorio de datos, el puerto del Postgres embebido y la ruta del archivo de configuración. Guarda estos datos en un archivo local del proyecto que tú controlas (nunca los repite en el chat). Un pequeño detalle que el brief indica al agente que debe hacer bien: el banner de onboarding etiqueta su línea de API con un sufijo /api, pero el agente captura el host base sin ese sufijo, para que las llamadas posteriores a la API no terminen con una ruta duplicada /api/api/. No necesitas rastrear esto tú mismo; es justo el tipo de detalle para el que existe el brief. En el modo predeterminado con enlace a loopback no se emite una clave de API bootstrap (la confianza queda limitada a loopback), y tu agente lo dirá si preguntas por qué no aparece ninguna clave. Cuando termina el onboarding, el dashboard suele abrirse automáticamente en tu navegador predeterminado.

1a termina cuando: el agente informa que el servidor de API está escuchando, puedes abrir la URL del dashboard en tu navegador y el dashboard se renderiza sin errores.

1b. Define tu primera empresa

Pega esto a tu agente:

Ahora define la empresa. Llámala Acme Customer Support. Su propósito: "Responder a las consultas de clientes en menos de 4 horas, con decisiones de reembolso tomadas de forma consistente y dentro de la política." Añade un objetivo, "Reducir el tiempo promedio de respuesta a menos de 4 horas," y un proyecto, "Triaje de correo electrónico entrante." Revisa primero la API viva para obtener los nombres exactos de los campos y luego créalos. Cuando termines, muéstrame qué es visible ahora en el dashboard.

El agente lee la sección Companies del brief y confirma los nombres de campo contra la API en ejecución (el brief señala que el propósito de la empresa va en un campo description, y que un nombre de campo desconocido falla en silencio en lugar de fallar ruidosamente). Luego crea la empresa, el objetivo y el proyecto, y te guía al dashboard para confirmar.

Terminas el escenario 1 cuando: tu dashboard muestra una empresa llamada "Acme Customer Support" con un objetivo y un proyecto, y el registro de actividad muestra las filas de creación correspondientes (tu agente leerá los nombres exactos de acción que registró Paperclip; se ven como company.created, goal.created, project.created). Toda acción futura se apoya en esta línea base.

Continuidad hacia el escenario 2

El ID de empresa que Paperclip asignó ya está en el archivo local del proyecto que creó el agente. Tu agente lee ese archivo en todos los escenarios posteriores, así que nunca necesitas recordar el ID tú mismo. Mantén tu agente ejecutándose en la carpeta descomprimida para que tenga ese archivo en su directorio de trabajo.

---

Escenario 2: contrata tu primer Worker (~15 min)

El concepto. Un Worker en Paperclip es un rol configurado: un nombre, un runtime, permisos, un presupuesto, un horario de heartbeat. (La propia API de Paperclip los llama "agents"; esta página dice "Worker" en todo momento para que nunca se confundan con el agente de codificación al que le pegas prompts. Cuando tu agente te muestra una solicitud a /agents, es lo mismo). El runtime se conecta mediante un adaptador. Paperclip incluye varios: runtimes LLM (claude_local, codex_local, gemini_local y más), un openclaw_gateway, un adaptador process que ejecuta un comando en cada heartbeat y un adaptador http que envía por POST cada heartbeat a una URL que controlas. Tu agente puede listar el conjunto actual con una llamada de API contra tu instalación.

Para este curso acelerado contratarás tu primer Worker en el adaptador http, apuntando a worker-stub.py, el Worker local sin clave incluido en tu descarga. Es un pequeño archivo Python que usa solo la biblioteca estándar. Cada vez que Paperclip le asigna trabajo, envía por POST el issue completo al stub; el stub lee el issue y publica una disposición de vuelta, lo que mueve el issue a done. Sin LLM, sin clave de API. La forma del pipeline (heartbeat, asignación, aprobación, auditoría) es exactamente la misma que tendría con un Worker LLM real; lo único distinto es que el producto de trabajo es una disposición de stub en vez de un borrador de respuesta. El escenario 5 es donde lo sustituyes por un Worker real respaldado por LLM.

Una nota sobre la autoridad. Cuando contrates el Worker, describirás lo que tiene permitido hacer en lenguaje natural en un campo capabilities: leer registros de CRM, redactar respuestas, los reembolsos superiores a $50 y el correo externo saliente necesitan aprobación de la junta. Piensa en eso como el sobre de autoridad del Worker. En la versión 2026 de Paperclip, ese sobre se almacena como la descripción que escribiste, no se aplica campo por campo en el runtime; el verdadero punto de aplicación es la compuerta de aprobación que conectarás en el escenario 4. El sobre sigue siendo el modelo mental correcto: es la línea que, cuando una tarea la cruza, debe producir una solicitud de aprobación en lugar de una acción.

Contratas definiendo el rol y registrándolo mediante la API. Dos prompts: iniciar el stub y redactar el rol; luego registrar y verificar.

2a. Inicia el Worker stub y redacta el rol

Primer prompt: orienta y luego redacta.

Quiero contratar un Worker llamado Tier-1 Customer Support, ejecutándose en el adaptador http apuntado al worker-stub.py que vino en esta carpeta. Primero, explícame qué hace worker-stub.py y cómo lo iniciarás. Luego muéstrame el cuerpo de solicitud agent-create desde tu brief antes de registrar nada: quiero ver el nombre del rol, el adaptador y su configuración, el texto de capabilities, los permisos, el presupuesto y el horario de heartbeat. Pon el presupuesto mensual deliberadamente bajo; el escenario 5 usará un Worker real para mostrar qué mide un presupuesto.

Tu agente lee la sección Agents del brief y explica worker-stub.py (es un pequeño servidor HTTP: escucha el POST de heartbeat de Paperclip, lee el issue dentro del payload y aplica PATCH con una disposición done de vuelta). Luego te muestra cómo lo iniciará (un comando python3, con un puerto de escucha y tu URL de API de Paperclip como argumentos). Después redacta el cuerpo agent-create y te muestra la estructura: name, adapterType (http) y adapterConfig (la URL del stub), capabilities (el texto de autoridad en prosa), permissions, budgetMonthlyCents y el horario de heartbeat bajo runtimeConfig. Léelo. Si un campo parece incorrecto, pregunta; el agente lo confirmará contra la API viva.

Segundo prompt: inicia, registra, verifica.

Se ve bien. Inicia el Worker stub, registra el rol con Paperclip y confirma que aparece en el dashboard. Muéstrame el ID de agente que asignó Paperclip, la hora del próximo heartbeat y el archivo de log propio del stub para que pueda ver que está escuchando.

El agente inicia worker-stub.py (lo deja ejecutándose en segundo plano, registrando cada heartbeat que recibe), registra el rol mediante la API, captura el ID de agente asignado en el archivo local del proyecto y te pide que actualices el dashboard.

Terminas el escenario 2 cuando: el dashboard muestra un Worker llamado "Tier-1 Customer Support", worker-stub.py está en ejecución y existe su archivo de log, y el registro de actividad muestra la fila de creación del Worker (tu agente leerá el nombre exacto de acción; se ve como agent.created). Una cosa que conviene saber desde el principio: los Workers de Paperclip son inmutables después de crearse. No puedes editar el adaptador ni el presupuesto de un Worker después; contratas uno nuevo. Por eso el escenario 5 contrata un Worker LLM nuevo en vez de actualizar este.

Continuidad hacia el escenario 3

Tu Worker está registrado y worker-stub.py está en ejecución, pero la cola de issues del Worker está vacía. El siguiente escenario le da trabajo real. Mantén el proceso stub en ejecución: si lo cierras, los heartbeats llegan a una URL muerta y los issues no se resolverán. Si paras por el día, tu agente puede reiniciar el stub cuando retomes el escenario 3.

---

Escenario 3: envía a la empresa su primer issue real (~15 min)

El concepto. La empresa existe, el Worker existe, pero no se ha asignado nada. En producción real, un correo de cliente dispararía un evento que crea un issue en Paperclip. Paperclip 2026 no tiene motor de enrutamiento basado en reglas: no existe una capa de "si el issue coincide con X, envíalo al Worker Y". La asignación es directa, e importa cuándo la haces. Un issue creado con un asignado en el momento de creación se conecta a la orquestación de heartbeat: nace listo, y el siguiente heartbeat lo recoge. Un issue creado sin asignado y luego asignado después no se recoge de la misma manera. Así que el movimiento es: crea el issue y nombra su Worker en el mismo paso.

Lo interesante ocurre después: se dispara el siguiente heartbeat del Worker, Paperclip envía por POST el issue completo a worker-stub.py, el stub lo lee y publica una disposición done, y el issue pasa de todo a in_progress y luego a done, con una fila del registro de actividad registrando cada paso.

Dos prompts: crear y asignar el issue, luego observar cómo lo recoge el Worker.

3a. Crea un issue entrante, asignado en el momento de creación

Pega esto a tu agente:

Crea un issue entrante para el proyecto "Triaje de correo electrónico entrante": un cliente (llámalo C-4429) pregunta por un reembolso de $30 por un producto que llegó dañado. Escribe la descripción como un correo realista de cliente de dos frases. Asígnalo a Tier-1 Customer Support en el momento de creación, en el mismo comando, no como una edición posterior. Cuando se cree, muéstrame el ID de issue que asignó Paperclip y en qué estado está ahora mismo.

Tu agente lee la sección Issues del brief, crea el issue con el Worker nombrado como asignado en el comando de creación y te muestra el identificador del issue (se ve como ACM-1).

3a termina cuando: la cola de issues del dashboard muestra un issue asignado a Tier-1 Customer Support, en estado todo, y el registro de actividad muestra la fila issue.created.

3b. Observa cómo lo recoge el Worker

Un aviso antes de pegar esto. El Worker que contrataste tiene configurado wake on assignment, así que asignar el issue en el momento de creación disparó un heartbeat de inmediato. Para cuando leas esto, el issue puede estar ya en done. Eso significa que el sistema funciona, no que te hayas saltado un paso. Por tanto, este prompt no es "haz que ocurra"; es "muéstrame lo que ya ocurrió, en el registro".

Pega esto a tu agente:

Muéstrame qué pasó ya con ese issue. Abre el archivo de log propio de worker-stub.py y las filas del issue en el registro de actividad, y explícame la secuencia: el heartbeat que se disparó al asignar, el stub recibiendo el issue, el stub publicando su disposición de vuelta y el issue llegando a un estado terminal. Dime qué campos prueban que el trabajo ocurrió de verdad en lugar de que el issue simplemente se haya cambiado a done. Si por alguna razón el issue aún no está done, dispara manualmente un heartbeat para Tier-1 y luego explícame la misma secuencia.

El agente lee ambos registros y narra la secuencia que ya se ejecutó: el Worker despertó con la asignación, Paperclip envió el issue al stub por POST, y el stub aplicó PATCH con una disposición done de vuelta. El issue está en done, con marcas de tiempo startedAt y completedAt. El registro de actividad registra la ejecución. (Si el horario de heartbeat no se hubiera disparado todavía, el brief también tiene el comando para un heartbeat bajo demanda, de modo que el agente puede activarlo sin esperar la cadencia).

Terminas el escenario 3 cuando: el issue pasó de todo por in_progress hasta done, el registro de actividad muestra la transición y el log de worker-stub.py muestra el heartbeat que recibió y la disposición que publicó de vuelta. No se registra costo contra este issue, lo cual es correcto: el escenario 5 cubre por qué, y dónde empieza a existir el dato de costo.

Continuidad hacia el escenario 4

Tu Worker ya tiene un issue completado, así que el registro de actividad ya no está vacío cuando agregues el paso de aprobación. El escenario 4 trabaja deliberadamente con un issue cuya acción (un reembolso grande) está por encima de lo que un Worker Tier-1 debería decidir solo, para mostrar cómo se presenta y registra una aprobación de la junta.

---

Escenario 4: presenta una aprobación para una acción riesgosa (~15 min)

El concepto. Algunas acciones están por encima del nivel de autoridad de un Worker Tier-1: un reembolso de $750, un cambio contractual, cualquier cosa que cruce el sobre de autoridad que describiste en el escenario 2. La respuesta de Paperclip es la aprobación: un registro rastreado de decisión de la junta. Un Worker LLM real, al razonar sobre un reembolso de $750, reconocería que la acción excede su autoridad y presentaría una solicitud de aprobación en lugar de actuar. Tu Worker stub sin clave no razona, así que en este escenario actúas como la mano de la junta: presentas la solicitud de aprobación que presentaría un Worker, y luego la decides.

Hay dos cosas que conviene decir con honestidad desde el inicio, porque definen qué significa "terminado" aquí:

• Una aprobación es un registro de decisión, no una máquina de estados. Presentar una aprobación no suspende un Worker, y aprobarla no reanuda automáticamente uno, no cambia el estado del issue vinculado ni ejecuta la acción aprobada. Actuar sobre la decisión es un paso separado y explícito. Lo que Paperclip te da es el registro duradero y auditado de quién decidió qué, con qué justificación y cuándo. Ese registro es lo valioso: es lo que lee un auditor seis meses después.
• El momento didáctico es la pista de auditoría, no un desbloqueo automático. Observa la fila en el registro de actividad, no esperes que el issue se mueva solo.

Dos prompts: presentar la solicitud y luego decidirla.

4a. Presenta la solicitud de aprobación

Pega esto a tu agente:

Crea un issue entrante: el cliente C-1138 pide un reembolso de $750 por un producto que compró hace tres meses; dice que llegó defectuoso y que tiene fotos. No lo asignes todavía a un Worker: esta es una acción que necesita aprobación de la junta antes de que alguien actúe. Luego, actuando como lo haría un Worker cuando encuentra una acción por encima de su autoridad, presenta una solicitud de aprobación de la junta vinculada a ese issue. Usa el tipo de aprobación para una decisión de la junta. En el payload, pon la acción ("emitir un reembolso de $750"), la justificación (el historial del cliente, las fotos del daño, la política sobre defectos documentados) y dos o tres alternativas consideradas (reembolso parcial, crédito en tienda, no reembolsar). Muéstrame la aprobación en estado pending y confirma que el issue en sí sigue intacto.

El agente crea el issue sin asignado (así el Worker stub nunca lo recoge; queda en su estado inicial predeterminado). Luego presenta la solicitud de aprobación mediante la API de aprobaciones de la empresa: el type de decisión de junta y un payload libre que lleva la acción, la justificación y las alternativas tal como fueron indicadas. Vincula la aprobación al issue. El registro de actividad recibe una fila approval.created.

4a termina cuando: el issue existe, sin asignar e intacto en su estado predeterminado, la cola de aprobaciones del dashboard tiene una entrada pending, y el agente se detiene para entregarte la decisión.

4b. Decídela

Esta parte es tuya. Lee la solicitud que presentó tu agente: el monto, la justificación, las alternativas. Decide.

Pega esto a tu agente después de decidir:

He decidido aprobar este reembolso (o: rechazarlo; dime cuál y por qué en una línea). Registra mi decisión. Luego explícame las filas del registro de actividad para esta aprobación y muéstrame el campo que prueba que yo, la junta humana, fui quien decidió, no un agente. Y recuérdame explícitamente qué no ocurrió automáticamente: el issue sigue donde estaba, y qué tendría que hacer después para actuar de verdad sobre esta decisión.

El agente registra tu decisión (la aprobación pasa a approved o rejected, con la identidad del decisor y una marca de tiempo de decisión estampadas). Te recorre el registro de actividad: la fila approval.approved (o approval.rejected), con actor_type establecido en user y un actor_id que identifica a la junta. Luego nombra la parte honesta: el issue vinculado no cambió de estado por sí solo. Si quieres que el issue se cierre o que el reembolso se "emita" (simulado, porque no hay procesador de pagos conectado), eso es un comando separado, y el agente lo hará si se lo pides.

Terminas el escenario 4 cuando:

• el registro de actividad contiene la cadena de aprobación (solicitud presentada, decisión registrada por ti),
• el issue vinculado sigue visiblemente sin cambios por la decisión,
• puedes nombrar el campo que distingue a un decisor humano de una acción de agente (actor_type), y
• puedes explicar con tus propias palabras por qué una aprobación es un registro de decisión y no un desbloqueo automático.

Continuidad hacia el escenario 5

Ahora tienes un registro de actividad pequeño pero real: dos issues, una aprobación, los heartbeats detrás de ellos. Sin embargo, una tabla sigue vacía: todavía no hay datos de costo. El escenario 5 es donde eso cambia, y es el único escenario que necesita una clave de API.

---

Escenario 5: sustituye por un Worker LLM real; dale fuerza al presupuesto (~15 min)

El concepto. Cada Worker tiene un presupuesto mensual, definido en centavos cuando lo contratas. Pero un presupuesto solo tiene algo que aplicar cuando un Worker hace trabajo facturable: el stub sin clave no hace ninguno, así que su gasto permanece en cero y su presupuesto nunca se mueve. Esa es la forma honesta de la cosa, no un bug del laboratorio. Para ver que un presupuesto mida algo de verdad, necesitas un Worker respaldado por un runtime LLM.

Así que este escenario hace el cambio. Contratarás un nuevo Worker en el adaptador gemini_local (una contratación nueva, no una edición, porque los Workers son inmutables, como señaló el escenario 2), le darás un presupuesto mensual deliberadamente pequeño y le apilarás trabajo suficiente para consumirlo. Luego observarás qué hace realmente Paperclip a medida que el gasto sube hacia el límite. Este es el único escenario que necesita una clave de API: una clave gratuita de Gemini, la misma que usa el curso acelerado de OpenClaw. Gemini es la ruta que recorre esta página porque el nivel gratuito mantiene el escenario cerca de lo sin clave. Si ya tienes una clave para otro runtime de bajo costo (codex_local con un modelo barato de OpenAI, por ejemplo), eso demuestra el mismo mecanismo de presupuesto, y tu agente puede ajustar el adaptador en consecuencia.

Un prompt para contratar el Worker LLM, otro para darle trabajo y observar el presupuesto.

5a. Contrata el Worker LLM

Pega esto a tu agente:

Quiero añadir ahora un Worker LLM real. Exportaré GEMINI_API_KEY en mi shell antes de que empieces: dime cuándo necesitas que lo haga. Contrata un Worker nuevo llamado Tier-1 Customer Support (LLM) en el adaptador gemini_local, usando el modelo Gemini capaz más barato actual. Dale un presupuesto mensual deliberadamente bajo, uno o dos dólares, para poder observar cómo se acumula el gasto contra él. Explícame el cuerpo de creación antes de registrarlo, y recuérdame por qué estamos contratando un Worker nuevo en lugar de editar el stub.

Tu agente te recuerda que los Workers son inmutables (por tanto, una contratación nueva, no una edición), nombra el momento en que necesitas exportar la clave y redacta el cuerpo agent-create: la misma forma que en el escenario 2, pero con adapterType establecido en gemini_local y un budgetMonthlyCents pequeño. Registra el Worker después de que hayas exportado la clave.

5b. Dale trabajo y observa el presupuesto

Pega esto a tu agente:

Ahora dale trabajo al Worker LLM. Crea unos diez issues cortos de soporte entrante, con algo de variedad, y asigna cada uno al nuevo Worker LLM en el momento de creación. Dispara heartbeats para que los procese. Sigue el log del servidor de Paperclip. Quiero ver dos cosas: que empiecen a existir los datos de costo por ejecución (no existían para el stub sin clave), y que el gasto mensual del Worker suba hacia el presupuesto que definí. Dime, en lenguaje claro, exactamente qué hace Paperclip cuando el gasto se acerca y luego cruza el límite: ese es el comportamiento que quiero observar.

El agente crea y asigna los issues, dispara heartbeats y sigue el log. Esta vez el Worker hace trabajo facturable, así que los datos de uso por ejecución empiezan a llegar a los registros de heartbeat, y el gasto mensual del Worker sale de cero. El agente narra qué hace realmente Paperclip mientras el presupuesto se agota y te lo informa con claridad: esta es una observación en vivo, no un resultado guionizado, y el trabajo de tu agente es decirte lo que ve.

Terminas el escenario 5 cuando:

• el nuevo Worker LLM resolvió issues reales,
• los datos de costo por ejecución existen donde antes estaban vacíos,
• el gasto mensual del Worker se movió contra el presupuesto que definiste, y
• tu agente te dijo en lenguaje claro qué hizo Paperclip cuando el presupuesto se acercó a su límite.

Una palabra sobre la clave de API

Exporta la clave en tu shell (export GEMINI_API_KEY=...); nunca la pegues en un archivo del proyecto, y nunca dejes que tu agente la escriba en uno. AGENTS.md le dice lo mismo a tu agente. Si alguna vez pegas una clave donde no corresponde, rótala. Una clave de nivel gratuito tiene bajo riesgo, pero el hábito es lo importante.

Continuidad hacia el escenario 6

Ahora tienes dos Workers (el stub sin clave y el respaldado por LLM), más de una docena de issues, una aprobación y, nuevo en este escenario, datos de costo reales. Es suficiente historia para que la consulta de auditoría del escenario 6 devuelva algo que valga la pena leer.

---

Escenario 6: consulta la pista de auditoría como un CFO (~10 min)

El concepto. El objetivo completo de un plano de gestión es que alguien fuera de la fuerza laboral (un CFO, legal, operaciones, cumplimiento) pueda reconstruir lo que ocurrió solo desde la base de datos, en segundos, sin preguntar a nadie. Paperclip guarda esa historia en una base de datos Postgres embebida. La tabla más importante es activity_log: una fila por acción mutante (empresa creada, issue creado, aprobación decidida, Worker contratado, heartbeat invocado), con el actor, la acción y la entidad que tocó. Una segunda tabla, cost_events, contiene la historia de dinero (proveedor, modelo, tokens, costo en centavos por ejecución facturable) y solo tiene filas una vez que un Worker LLM ha hecho trabajo facturable, por eso estuvo vacía hasta el escenario 5.

Un prompt: abrir Postgres, ejecutar la consulta de historia y la consulta de costo, leer las respuestas.

Pega esto a tu agente:

Hora de jugar al CFO. Conéctate al Postgres embebido de Paperclip (tu brief cubre cómo construir la cadena de conexión). Primero, ejecuta la consulta "qué ocurrió, en orden" contra activity_log para nuestra empresa: cada acción con su actor y la entidad que tocó, de la más antigua a la más reciente. Luego ejecuta la consulta de costo contra cost_events: costo total de hoy, en dólares. Muéstrame el SQL y los resultados de ambas. Por último, explícame una fila de activity_log para la aprobación que decidí en el escenario 4, y señala los campos que un auditor usaría para confirmar que yo fui quien decidió.

El agente lee la sección Audit-trail del brief, construye la cadena de conexión de Postgres desde el archivo de configuración de tu instalación (no hay un comando atajo para esto; el brief muestra cómo) y ejecuta dos consultas:

1. Qué ocurrió, en orden: un SELECT sobre activity_log filtrado a tu empresa, ordenado por tiempo. Devuelve la columna vertebral completa de tu ejecución: la creación de la empresa y el proyecto, ambos Workers contratados, cada issue creado, los heartbeats, la aprobación presentada y decidida. Esta es la consulta que funciona sin ningún Worker LLM; es el corazón sin clave de la historia de auditoría.

2. Costo total de hoy: un SELECT SUM(...) sobre cost_events, convirtiendo la columna entera de centavos a dólares, filtrado a hoy. Antes del escenario 5 no devolvía nada; ahora devuelve el costo real (pequeño) de las ejecuciones de tu Worker LLM.

Después, el agente te muestra una fila de activity_log para la aprobación que decidiste: la acción (approval.approved o approval.rejected), actor_type establecido en user, el actor_id que identifica a la junta y la marca de tiempo. Así reconstruye tu decisión un auditor.

Terminas el escenario 6 cuando: la consulta de historia devuelve el relato ordenado de toda tu ejecución, la consulta de costo devuelve un número real del Worker del escenario 5, y puedes nombrar la columna de activity_log (actor_type) que distingue una decisión humana de una acción de agente.

---

Escenario 7: tu auditoría mensual de fuerza laboral (~10 min/mes)

El concepto. Una empresa se acumula con el tiempo: Workers contratados, presupuestos fijados, aprobaciones decididas, horarios en ejecución. Cada adición fue una decisión pequeña que aprobaste; la cadena se compone. La defensa no es la vigilancia en cada paso (nunca detectarías lo que todavía no existe); es una revisión de diez minutos con cadencia fija. Este escenario no forma parte de tus primeros noventa minutos; es el movimiento que harás una vez al mes durante el resto de la vida de la empresa.

Pega esto a tu agente (cuando llegue el momento):

Ejecuta mi auditoría mensual de fuerza laboral de Paperclip. Recorre todo lo que se haya contratado, configurado, programado, decidido o pausado desde la última auditoría. Marca cualquier cosa que no haya aprobado explícitamente, cualquier Worker que no haya hecho trabajo productivo, cualquier presupuesto que se haya desviado de donde lo definí y cualquier configuración más laxa de lo que debería. Resume todo como un informe breve único que pueda aprobar o recortar.

Tu agente lee el registro de actividad, la lista actual de Workers, los presupuestos y las tablas de auditoría, y produce un informe de una página.

Termina cuando: has dedicado diez minutos a revisar el informe y has tomado al menos una decisión (ajustar el texto de autoridad de un Worker, recortar un presupuesto, retirar un Worker sin uso, elevar un umbral de aprobación). Marca tu calendario para el próximo mes.

---

Por qué esto funciona

Dos cosas se mantienen frescas; una cosa se mantiene duradera.

Fresco #1: Los escenarios de esta página viven en el sitio del libro. Tu agente los lee cuando le dices en qué escenario estás.

Fresco #2: Los comandos y la forma de API actuales de Paperclip viven en paperclip.ing/llms.txt, un índice de la documentación completa apto para LLM, además de docs.paperclip.ing para el recorrido pausado. Tu agente los lee frescos antes de cualquier operación no trivial. Paperclip avanza rápido; así el brief se mantiene preciso incluso cuando cambian flags individuales.

Duradero: La carpeta que descargaste contiene AGENTS.md (qué es Paperclip, cómo navegar su documentación, las barandillas de seguridad, las formas operativas verificadas, los patrones de recuperación), CLAUDE.md (el marcador de importación de una línea) y worker-stub.py (el propio Worker sin clave). AGENTS.md cubre empresas, Workers y adaptadores, el contrato de heartbeat, issues y asignación, aprobaciones, presupuestos, auditoría y diagnóstico. Es más largo que esta página porque cubre todo lo que se le podría pedir a un agente de codificación con Paperclip, no solo los seis escenarios anteriores. Nada en la carpeta se vuelve obsoleto, así que la descargas una vez y la reutilizas.

El patrón es pequeño por diseño: una referencia operativa, un marcador de importación, un Worker ejecutable. Tres archivos. La inteligencia no está en los archivos; está en tu agente de codificación leyéndolos y aplicándolos a lo que pidas después. No recorriste seis demos desconectadas; ensamblaste una empresa que tocarás mañana.

---

Qué está ejecutándose ahora

No son seis demos: es un sistema en ejecución. Inventario de lo que persiste después del escenario 6:

Artefacto	Qué es realmente	Por qué importa mañana
Servidor de Paperclip	Un proceso Node.js de larga ejecución que contiene la API y el Postgres embebido	Tu empresa sobrevive al cierre de la terminal y al reinicio
El directorio de datos	Todos los datos de tu empresa, secretos cifrados, logs del servidor	El sustrato; respalda este directorio como respaldarías tus dotfiles
Una empresa	Un propósito, un objetivo, un proyecto y el aislamiento con alcance de empresa	El límite dentro del que viven cada Worker, issue y aprobación
Dos Workers	El Worker worker-stub.py sin clave y el Worker LLM gemini_local	Un Worker prueba el pipeline sin clave; el otro muestra la economía
worker-stub.py	Un pequeño proceso HTTP local, escuchando heartbeats	Tu primer Worker y la plantilla para cualquier Worker sin clave que escribas
Issues y el registro de actividad	Issues asignados y trabajados, más el registro fila por fila de cada acción	Comportamiento reproducible de la fuerza laboral, historia consultable
Una aprobación	Una decisión de junta presentada y decidida, registrada permanentemente	La aprobación auditada que usa tu fuerza laboral para acciones riesgosas
Un presupuesto con datos	El presupuesto mensual del Worker LLM, con gasto real medido contra él	El número que hace aplicable "sin gasto descontrolado" en lugar de decorativo
Consultas de auditoría ejecutables	SQL sobre activity_log (y cost_events) que responde rápido preguntas de partes interesadas	La vista que un CFO, legal o cumplimiento puede usar sin preguntarte
AGENTS.md y la línea de recuperación	El brief duradero que tu agente lee en cada sesión	La habilidad que reutilizas durante toda la vida de esta empresa

Un día de trabajo con esto se ve así:

1. llega un mensaje real de cliente;
2. una integración (que tú conectarás más adelante) crea un issue de Paperclip asignado a un Worker;
3. el siguiente heartbeat lo lleva al Worker;
4. el Worker redacta una respuesta;
5. decides los casos de alto riesgo en el dashboard;
6. una vez al mes ejecutas la auditoría.

Si alguno de esos artefactos desaparece más adelante (borrado del portátil, eliminación accidental, actualización de versión fallida), el brief más un onboarding fresco y una restauración del directorio de datos desde backup te devuelven a esta misma imagen.

Antes de conectar un canal real de clientes

El curso acelerado es de usuario único: tú eres la junta humana, y tú creas issues para pruebas. Conectar una fuente entrante real (una bandeja de soporte, un formulario de contacto, un evento desde tus sistemas existentes) significa que personas desconocidas pueden escribir dentro de tu fuerza laboral. Antes de hacer eso, dos cosas deben ser ciertas. Cada Worker que procesa contenido entrante debe tener un sobre de autoridad estricto y descrito con claridad (sin latitud amplia solo porque el trabajo es "soporte al cliente"). Y necesitas un plan deliberado para entradas que no mapean a ningún Worker (sin issues huérfanos). Quédate en modo de usuario único hasta haber pensado ambas cosas.

---

A dónde ir después

Después del escenario 6, tienes una empresa funcional nativa de IA: dos Workers, una aprobación demostrada, un presupuesto con datos reales detrás y una pista de auditoría que responde preguntas de partes interesadas en segundos. Esa es la mayor parte de la superficie que la mayoría de la gente necesita para empezar.

Para el recorrido pausado de cualquier tema que esta página haya tocado (o cualquier cosa que haya saltado), hay varios cursos acelerados más profundos junto a este en el directorio de primeros pasos. Mapa rápido:

Quieres...	Ve a
Envolver un solo Worker en un motor de flujo de trabajo duradero antes de gestionar una flota	De Digital FTE a Worker de producción: la envoltura de durabilidad de Inngest
Convertir la contratación en una capacidad invocable (Workers que contratan otros Workers bajo política)	De fuerza laboral fija a dinámica: el sucesor de este curso
Usar la API REST de Paperclip como herramientas desde dentro de otro agente	Revisa docs.paperclip.ing para el paquete actual de servidor MCP; fija la versión
Desplegar Paperclip en la nube o en un host compartido (varias máquinas, varios usuarios)	La documentación viva en docs.paperclip.ing; verifica qué se ha lanzado antes de depender de ello
Conectar OpenClaw como la capa de borde entre humanos y tu fuerza laboral	El curso acelerado de OpenClaw

Para todo lo demás, tu AGENTS.md ya cubre la mayor parte de la plataforma. Pregunta a tu agente de codificación: "¿Qué dice AGENTS.md sobre el contrato de heartbeat?" o "Explícame la sección de aprobaciones de AGENTS.md." El brief es la referencia; esta página es el recorrido.

La metalección: lo más valioso en tu carpeta descomprimida es AGENTS.md. Dedica una tarde a leerlo de extremo a extremo (no por los pasos de instalación, sino por la forma del documento: la tabla de descubrir antes de actuar, el patrón de trabajo, las operaciones por tipo de tarea, las listas de diagnóstico). Luego escribe uno para cualquier herramienta que pongas después frente a un agente de codificación. El patrón es portable: toda herramienta con una superficie aprendible merece un AGENTS.md. Paperclip fue un objetivo limpio porque la instalación se beneficia de una configuración impulsada por agente y las operaciones se descomponen en escenarios de pegar y observar; encontrarás otros. Escribe el siguiente.

---

Ayuda de estudio con flashcards