Introducción a ClawSpec + OpenSpec: Automatice y mantenga sus proyectos en marcha de forma continua, sin interrupciones ni intervención manual

Dificultad: Principiante | Duración: 20 minutos | Beneficio: Gestione todo el ciclo de vida del proyecto con OpenSpec desde la ventana de chat, permitiendo que la IA trabaje continuamente sin bloqueos.

---

Público objetivo

Ya ha puesto en marcha OpenClaw y lo utiliza para tareas cotidianas. Durante el proceso, es probable que se haya encontrado con este problema:

Los requisitos se explicaron claramente, el agente aceptó comenzar, pero después de un momento se detiene y no avanza hasta que usted lo presiona.

Este problema es especialmente evidente en tareas a largo plazo, cambios de requisitos o escenarios donde se construye mientras se conversa. No solo necesita una IA que sepa chatear, sino un sistema de ejecución que organice los requisitos, avance continuamente, no requiera supervisión constante y pueda recuperarse automáticamente.

Lectores objetivo de este artículo:

• Usuarios de OpenClaw que desean completar el ciclo total del proyecto (Requisitos → Planificación → Código → Archivo) dentro del chat.
• Quienes han experimentado estancamientos después de que el agente inicia y buscan una solución de ejecución continua controlable.
• Interesados en el flujo de trabajo de OpenSpec que desean integrarlo directamente en OpenClaw.

---

Dependencias y entorno principales

Repositorio GitHub: https://github.com/bytegh/clawspec

---

Estructura completa del proyecto

Estructura del directorio del plugin ClawSpec (tras la instalación):

clawspec/
├── index.ts                    # Entrada del plugin
├── src/                       # Código fuente principal
│   ├── service/               # Capa de servicios
│   ├── watcher/               # Gestión del watcher de segundo plano
│   ├── stores/                # Almacenamiento de estado
│   └── hooks/                 # Hooks de OpenClaw
├── skills/                    # Textos de skills de OpenSpec (integrados)
├── test/                      # Casos de prueba
├── openclaw.plugin.json       # Configuración del plugin
├── package.json
└── tsconfig.json

Durante la ejecución, se generarán archivos de gestión de OpenClaw bajo cada repositorio:

<repo>/
├── .openclaw/clawspec/        # Estado de ejecución de ClawSpec
│   ├── state.json             # Estado actual del proyecto
│   ├── execution-control.json # Control de ejecución de cs-work
│   ├── execution-result.json  # Resultado de la ejecución
│   ├── worker-progress.jsonl  # Logs de progreso del segundo plano
│   ├── planning-journal.jsonl  # Registro de discusión de requisitos
│   ├── planning-journal.snapshot.json  # Instantánea del journal
│   ├── rollback-manifest.json # Manifiesto de reversión
│   ├── snapshots/             # Líneas base de instantáneas de cambios
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # Cambios archivados
├── openspec/                  # Directorio de especificaciones OpenSpec
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

Pasos detallados

Paso 1: Instalar el plugin ClawSpec

ClawSpec ofrece tres métodos de instalación; se recomienda el primero:

Opción A: Mediante el instalador de plugins de OpenClaw (Recomendado)

openclaw plugins install clawspec@latest

Opción B: Mediante ClawHub CLI

npx clawhub@latest install clawspec

Opción C: Instalación manual mediante paquete npm (Alternativa)

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest siempre resolverá a la última versión publicada de ClawSpec en npm. Si desea instalar un commit en desarrollo no publicado, use un checkout local o un paquete .tgz descargado.

---

Paso 2: Configurar OpenClaw

Tras la instalación, debe habilitar ACP y configurar ClawSpec en ~/.openclaw/openclaw.json:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

Descripción de opciones clave:

Si su OpenClaw no incluye ACPX, ClawSpec instalará automáticamente una copia local del plugin. ClawSpec gestiona la ruta del comando ACPX, por lo que no requiere configuración adicional.

Tras configurar, reinicie el gateway:

openclaw gateway restart
openclaw gateway status

---

Paso 3: Vincular workspace y proyecto

ClawSpec recuerda el workspace por canal de chat; cada canal puede vincularse a un directorio raíz de proyecto diferente.

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

Resultados esperados:

• ClawSpec registra la ruta del workspace en el canal de chat actual.
• Si el directorio demo-app no existe, se creará automáticamente.
• La primera vez que se seleccione este repo, se ejecutará automáticamente openspec init.

---

Paso 4: Crear un cambio OpenSpec e ingresar al contexto del proyecto

/clawspec proposal add-login-flow "Build login and session handling"

Este comando realiza tres acciones:

1. Crea el andamiaje estándar bajo openspec/changes/add-login-flow/ (proposal.md, design.md, tasks.md, specs/).
2. ClawSpec toma una instantánea de línea base de los archivos rastreados (para futuras reversiones).
3. El chat actual entra en el contexto del cambio activo add-login-flow.

A partir de aquí, todo el contenido del chat, mientras esté en estado "attached" (vinculado), se escribirá automáticamente en el planning journal.

---

Paso 5: Describir requisitos en el chat

Describa sus requisitos normalmente en el chat, por ejemplo:

Soporte para inicio de sesión con correo y contraseña.
Se requiere refresh token.
El access token debe expirar en 15 minutos.

ClawSpec añadirá este contenido a planning-journal.jsonl. En esta etapa no se actualizarán los artefactos ni se escribirá código inmediatamente; esta fase es solo para registro.

Si desea que el proceso continúe en segundo plano pero quiere usar la ventana actual para otros asuntos, use:

cs-detach

Esto separará el chat normal del planning journal, pero las notificaciones de progreso del watcher continuarán. Para volver a vincularlo, use:

cs-attach

---

Paso 6: cs-plan, sincronización visible de la planificación

Cuando considere que los requisitos están claros, ejecute:

cs-plan

ClawSpec actualizará directamente estos artefactos en el turno de chat visible actual:

• proposal.md — Propuesta del proyecto
• design.md — Diseño de arquitectura
• specs/ — Especificaciones detalladas
• tasks.md — Lista de tareas

cs-plan no utiliza el worker ACP de segundo plano ni depende de subagentes ocultos: podrá ver el proceso de actualización de artefactos por la IA directamente en la ventana principal.

---

Paso 7: cs-work, iniciar la implementación continua en segundo plano

Una vez que la planificación esté sincronizada y limpia, inicie la implementación:

cs-work

cs-work no escribirá código directamente en la ventana de chat; sigue esta cadena:

1. Verifica que el estado de planificación esté limpio (un journal sucio será interceptado).
2. Escribe en execution-control.json, activando el watcher.
3. El watcher inicia una sesión de worker ACP vía acpx.
4. El worker ejecuta las tareas de tasks.md una a una, actualiza el progreso y escribe en worker-progress.jsonl.
5. El watcher traduce los eventos de progreso del worker en mensajes cortos de chat para usted.

Recibirá mensajes de este tipo en su ventana de chat:

[Watcher] ACP worker connected...
[Worker] Preparing login-flow: loading context
[Worker] Loaded proposal.md
[Worker] Context ready for Task 1
[Worker] Task 1/5 complete: Módulo de autenticación de usuario
[Worker] Task 2/5 complete: Lógica de refresco de Token
...
[Worker] All tasks complete.

---

Paso 8: Seguimiento y recuperación de progreso

Esta es una de las capacidades centrales de ClawSpec: tras un reinicio del gateway, el worker se reconecta automáticamente.

Cuando el gateway se reinicia, el gestor del watcher:

• Escanea todos los proyectos activos.
• Prioriza el intento de retomar sesiones de worker ACP que sigan vivas.
• Si el worker antiguo ha muerto, rearma e inicia automáticamente un worker de reemplazo.
• Mantiene el progreso de las tareas y el desplazamiento (offset) del progreso del worker.

Es decir, no necesita presionar cs-work manualmente tras reiniciar el gateway. ClawSpec retomará el trabajo interrumpido automáticamente.

Para ver el estado del worker en tiempo real:

/clawspec worker status

Esto mostrará:

• El agente worker configurado actualmente.
• Estado de la capa de transporte (connected / disconnected).
• Fase de inicio (loading context / ready / running).
• PID en tiempo real, latido (heartbeat) y sugerencia del siguiente paso.

Ante fallos del worker ACP, ClawSpec distingue entre "errores recuperables" y "bloqueos reales", realizando reintentos limitados con retroceso (backoff) para los recuperables. Si se supera el límite de reintentos (por defecto 10), el proyecto se marca como blocked y requiere intervención manual.

Pausa y reanudación colaborativa:

cs-pause        # Pausa al worker en un límite seguro
cs-continue     # Reanuda la planificación o implementación

---

Paso 9: Archivado y cierre

Cuando todas las tareas estén completas, limpie el cambio activo:

/clawspec archive

Esto permitirá:

1. Validar la integridad del cambio OpenSpec.
2. Mover el cambio completado al directorio archives/.
3. Limpiar el estado del cambio activo en el chat actual.

Si desea descartar el cambio actual (sin conservar los cambios de código):

/clawspec cancel

ClawSpec restaurará los archivos rastreados desde la instantánea de línea base, en lugar de realizar un git reset --hard a nivel de todo el repositorio.

Ciclo de trabajo completo:

Discutir requisitos → cs-plan → cs-work → Esperar progreso → cs-detach (opcional) → cs-attach (opcional) 
→ /clawspec archive (al finalizar)

---

Resolución de problemas comunes

1. cs-work indica que "se requiere planning sync"

Causas:

• El planning journal está sucio (se discutieron nuevos requisitos tras la instantánea).
• Faltan artefactos de planificación o están desactualizados.
• El estado de aplicación de OpenSpec sigue bloqueado.

Solución:

cs-plan
# Esperar a que la planificación termine
cs-work

---

2. El Watcher indica que ACPX no está disponible

Causas posibles:

• acp.enabled no está activado.
• acp.backend no es acpx.
• acp.defaultAgent no está configurado.
• OpenClaw no incluye ACPX y ClawSpec no encontró una copia usable.

Solución rápida:

openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw gateway restart
cs-work

Si ACPX sigue sin estar disponible, ClawSpec intentará instalar una copia local. La primera instalación puede requerir tiempo y acceso a la red.

---

3. El chat normal contaminó el planning journal

Conversaciones normales se registraron en el journal y ahora bloquean cs-work por estar sucio.

Separar inmediatamente:

cs-detach

Cuando quiera volver a discutir requisitos:

cs-attach

---

4. El Worker está conectado pero no inicia las tareas

Esto suele indicar que el worker ACP está vivo pero sigue procesando el prompt de implementación o leyendo artefactos.

Revise prioritariamente estos mensajes:

• Estado del Watcher: "starting worker", "ACP worker connected...".
• Estado de carga del Worker: "Preparing <task>: loading context", "Loaded proposal.md", "Context ready...".

Si ve "Context ready for ...", el worker ha terminado de leer los artefactos y procederá con la primera tarea.

Ejecute /clawspec worker status y observe los campos startup phase y startup wait para determinar en qué paso está detenido.

---

5. Error del Worker "stdin is not a terminal" o sesión creada sin resultado

Causas:

• Existe una configuración de agente personalizada en ~/.acpx/config.json (ej. agents.codex apuntando a una ruta CLI local).
• acpx no puede iniciar el agente mediante CLI pura en entornos no interactivos.

Ejecutar diagnóstico:

/clawspec doctor

Si reporta problemas de configuración, ejecute la reparación automática:

/clawspec doctor fix

Reparación manual: Edite ~/.acpx/config.json y establezca "agents" como un objeto vacío:

{
  "agents": {}
}

---

6. /clawspec use indica que ya existe un cambio inacabado

Comportamiento esperado. ClawSpec no permite abandonar silenciosamente un cambio activo en el mismo repositorio.

Elija una opción:

/clawspec continue      # Continuar con el cambio actual
/clawspec archive       # Archivar cambio completado
/clawspec cancel        # Descartar cambio actual

---

Lectura extendida / Direcciones avanzadas

1. Uso avanzado de OpenSpec CLI

El OpenSpec CLI integrado es en sí mismo un sistema completo de gestión de especificaciones. Puede ejecutar directamente en el directorio del proyecto:

openspec status        # Ver estado del cambio actual
openspec diff          # Comparar archivos actuales con la línea base
openspec validate      # Validar la integridad de la especificación OpenSpec

Comprender la cadena propuesta → diseño → especificación → tarea → aplicación le permitirá planificar mejor la granularidad de sus cambios.

2. Gestión paralela de múltiples canales y proyectos

El workspace se recuerda por canal, lo que permite:

• Canal de Telegram para el backend.
• Canal de Discord para el frontend.
• El mismo repositorio puede tener diferentes cambios activos en distintos canales (aunque globalmente un repositorio solo permite un cambio inacabado a la vez).

Use cs-detach para dejar que el trabajo en segundo plano corra sin necesidad de supervisión constante en cada canal.

3. Configuración de agentes personalizados para el worker ACP

Además del acp.defaultAgent global, puede cambiar el agente del worker para un canal/proyecto específico:

/clawspec worker codex    # Usar codex para este canal/proyecto
/clawspec worker claude  # Volver a claude

Si tiene múltiples configuraciones de agentes (modelos con distintos niveles de capacidad), esto le permite elegir el worker adecuado según la complejidad de la tarea.

4. Sinergia con otras herramientas de OpenSpec

Los archivos tasks.md y proposal.md generados pueden ser leídos por otras herramientas (como Superpowers o scripts de CI personalizados), cerrando el ciclo de gestión. Los archivos de OpenSpec son Markdown puro, un formato abierto no ligado a una interfaz específica.

5. Personalización de la configuración de ClawSpec

plugins.entries.clawspec.config incluye opciones avanzadas como:

{
  "clawspec": {
    "enabled": true,
    "config": {
      "archiveDirName": "archives",
      "allowedChannels": ["ch_xxx", "ch_yyy"]
    }
  }
}

El campo allowedChannels permite restringir ClawSpec a canales específicos, ideal para entornos de equipo donde no todos los canales requieren este flujo de trabajo.