Creación de agentes de IA personalizados con OpenClaw: Guía para desarrolladores

Crear un agente de IA listo para producción no es lo mismo que escribir un chatbot. Los agentes deben percibir el contexto, razonar sobre información incompleta, ejecutar planes de varios pasos y recuperarse de fallas, todo sin supervisión humana. OpenClaw es una plataforma de agentes de IA empresarial creada específicamente para este nivel de autonomía operativa, que brinda a los desarrolladores un tiempo de ejecución estructurado, un modelo de composición de habilidades y una observabilidad de primera clase desde el primer día.

Esta guía está escrita para ingenieros que desean pasar de cero a un agente OpenClaw implementado y monitoreado. Cubrimos los aspectos internos de la arquitectura, la creación de habilidades, la gestión de la memoria, los enlaces de orquestación y los patrones de implementación que mantienen a los agentes confiables bajo la carga de producción.

Conclusiones clave

Los agentes OpenClaw están compuestos por Habilidades (capacidades atómicas), capas de Memoria y un Orquestador que planifica secuencias de ejecución.

El archivo de manifiesto del agente declara todas las dependencias, permisos y enlaces de herramientas antes del tiempo de ejecución.

Las habilidades son funciones sin estado que aceptan entradas escritas y emiten salidas escritas; la capacidad de prueba está incorporada.

Los niveles de Memoria de trabajo, Memoria de episodio y Memoria a largo plazo atienden diferentes necesidades de retención y recuperación.

Los ganchos (pre-ejecución, post-ejecución, en caso de error) le permiten inyectar monitoreo, limitación de velocidad y lógica alternativa sin modificar el código de habilidad principal.

El modo Sandbox de OpenClaw le permite reproducir rastros de producción localmente para depurar sin llamadas API en vivo.

Las transferencias entre múltiples agentes utilizan un bus de mensajes escrito, sin pasar cadenas sin formato entre agentes.

ECOSIRE proporciona implementaciones administradas de OpenClaw, bibliotecas de habilidades personalizadas y optimización continua para equipos empresariales.

Comprender el modelo del agente OpenClaw

Cada agente OpenClaw es una composición de cuatro primitivos: Habilidades, Memoria, Herramientas y un Orquestador.

Habilidades son las unidades atómicas de capacidad del agente. Una habilidad es una función que acepta un esquema de entrada escrito y devuelve un esquema de salida escrito. Las habilidades pueden ser sincrónicas o asincrónicas y declaran explícitamente sus dependencias externas. Ejemplos: ParseInvoice, SendSlackMessage, QueryCRMContact, GenerateReport.

Las herramientas son enlaces externos del sistema. OpenClaw viene con herramientas integradas para API REST, bases de datos, sistemas de archivos, navegadores y colas de mensajes. Usted registra herramientas en el Manifiesto del agente y las inyecta en habilidades en tiempo de ejecución mediante inyección de dependencia.

La memoria está organizada en tres niveles. La memoria de trabajo contiene el estado actual de la tarea: el bloc de notas del agente. Episodio Memoria almacena historiales de tareas completadas que se pueden recuperar por similitud semántica dentro de la sesión actual. La memoria a largo plazo persiste durante las sesiones y almacena los datos aprendidos, las preferencias del usuario y el conocimiento del dominio.

El Orquestador es el núcleo del razonamiento. Recibe una declaración de objetivos, consulta el registro de habilidades disponibles, crea un plan de ejecución y monitorea cada paso. Cuando una habilidad falla, el orquestador decide si vuelve a intentarlo, la sustituye por una habilidad alternativa o la escala a un humano.

El diagrama de arquitectura para un único agente se ve así:

User Request
     ↓
[ Orchestrator ]
     ↓ plan
[ Skill Selector ] → [ Skill Registry ]
     ↓ execute
[ Skill Instance ]
     ↓ tool calls
[ Tool Layer ] → [ External Systems ]
     ↓ result
[ Memory Writer ]
     ↓ store
[ Working / Episode / Long-Term Memory ]
     ↓ next step or done
[ Orchestrator ] → response

Este ciclo continúa hasta que el orquestador determina que se cumple el objetivo o se alcanza una condición de parada.

Configuración de su entorno de desarrollo

Antes de escribir su primera habilidad, necesita el SDK de OpenClaw y un tiempo de ejecución del agente local.

npm install @openclaw/sdk @openclaw/runtime @openclaw/cli
npx openclaw init my-agent --template=typescript

El comando init genera un proyecto con esta estructura:

my-agent/
  agent.manifest.json   # Agent declaration
  skills/               # Skill implementations
  tools/                # Tool registrations
  memory/               # Memory adapter config
  tests/                # Skill and integration tests
  .openclaw/            # Local runtime state

El agent.manifest.json es el archivo más importante. Declara todo lo que OpenClaw necesita para iniciar su agente:

{
  "name": "invoice-processor",
  "version": "1.0.0",
  "runtime": "node-20",
  "skills": [
    "skills/extract-line-items.ts",
    "skills/validate-vendor.ts",
    "skills/post-to-erp.ts"
  ],
  "tools": {
    "erp": { "type": "rest", "baseUrl": "${ERP_BASE_URL}", "auth": "bearer" },
    "storage": { "type": "s3", "bucket": "${DOCS_BUCKET}" }
  },
  "memory": {
    "working": { "ttl": 3600 },
    "episode": { "backend": "redis", "maxItems": 500 },
    "longTerm": { "backend": "postgres", "table": "agent_facts" }
  },
  "permissions": ["read:invoices", "write:erp", "read:vendors"]
}

Las variables de entorno se inyectan en tiempo de ejecución y nunca se almacenan en el manifiesto.

Escribir tu primera habilidad

Las habilidades siguen un contrato estricto. Aceptan un objeto input que coincide con un esquema declarado, reciben tools y memory inyectados y devuelven un objeto output o arrojan un SkillError escrito.

import { defineSkill, SkillError } from "@openclaw/sdk";
import { z } from "zod";

const ExtractLineItemsInput = z.object({
  documentUrl: z.string().url(),
  documentType: z.enum(["invoice", "receipt", "purchase-order"]),
});

const ExtractLineItemsOutput = z.object({
  lineItems: z.array(
    z.object({
      description: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
      total: z.number(),
    })
  ),
  confidence: z.number().min(0).max(1),
});

export const ExtractLineItems = defineSkill({
  name: "extract-line-items",
  description: "Extracts line items from a document using OCR and LLM parsing",
  input: ExtractLineItemsInput,
  output: ExtractLineItemsOutput,
  tools: ["storage"],
  async run({ input, tools, memory }) {
    const fileBuffer = await tools.storage.get(input.documentUrl);
    if (!fileBuffer) {
      throw new SkillError("DOCUMENT_NOT_FOUND", `No document at ${input.documentUrl}`);
    }

    // OCR + LLM extraction logic here
    const extracted = await runOcrPipeline(fileBuffer);

    await memory.working.set("lastExtraction", extracted);

    return {
      lineItems: extracted.items,
      confidence: extracted.confidence,
    };
  },
});

Reglas de diseño clave para las habilidades:

Sin efectos secundarios en la entrada: las habilidades no deben modificar sus objetos de entrada.
Errores escritos: siempre lanza SkillError con un código legible por máquina, no Error genérico.
Declarar dependencias de herramientas: Solo se inyectan las herramientas declaradas en la matriz tools. Las herramientas no declaradas provocan un error de validación de inicio.
Escribir en la memoria explícitamente: las habilidades no persisten automáticamente en el estado. Llame a memory.working.set() deliberadamente.

Gestión de la memoria en la práctica

Los tres niveles de memoria tienen diferentes propósitos y elegir el nivel correcto es fundamental para la corrección del agente.

Memoria de trabajo es un almacén de valores-clave en proceso que permanece activo durante la ejecución de una sola tarea. Úselo para pasar resultados intermedios entre habilidades sin pasar por la cadena de producción. Se borra automáticamente cuando el orquestador finaliza o se agota el tiempo de espera.

// Skill A writes
await memory.working.set("vendorId", "VND-4521");

// Skill B reads
const vendorId = await memory.working.get("vendorId");

Episode Memory es un almacén de búsqueda semántica. Cuando se completa una tarea, el orquestador escribe opcionalmente un resumen incrustado en la memoria del episodio. Las tareas futuras pueden recuperar episodios pasados similares para informar su razonamiento.

// Query past episodes
const relatedEpisodes = await memory.episode.search(
  "invoice from Acme Corp with disputed line items",
  { topK: 3, minScore: 0.75 }
);

La memoria a largo plazo es la base de conocimientos persistente de su agente. Úselo para datos que deberían sobrevivir en todas las sesiones: reglas de categorización de proveedores, preferencias de usuario, restricciones de dominio aprendidas.

// Store a learned fact
await memory.longTerm.upsert({
  key: `vendor:${vendorId}:paymentTerms`,
  value: "NET-30",
  source: "invoice-2024-0312",
  confidence: 0.9,
});

Un error común es sobrescribir en la memoria a largo plazo. Guárdelo para hechos estables y de alta confianza. El razonamiento efímero pertenece a la memoria de trabajo.

Ganchos del ciclo de vida para la observabilidad y el control

OpenClaw expone cuatro ganchos de ciclo de vida por ejecución de habilidad: preRun, postRun, onError y onTimeout. Registre ganchos en el manifiesto del agente o mediante programación en su archivo de arranque.

import { AgentRuntime } from "@openclaw/runtime";

const agent = new AgentRuntime({ manifest: "./agent.manifest.json" });

agent.useHook("preRun", async (ctx) => {
  ctx.metadata.startTime = Date.now();
  console.log(`[${ctx.skill}] starting with input keys: ${Object.keys(ctx.input)}`);
});

agent.useHook("postRun", async (ctx) => {
  const elapsed = Date.now() - ctx.metadata.startTime;
  metrics.record("skill.duration", elapsed, { skill: ctx.skill });
});

agent.useHook("onError", async (ctx) => {
  if (ctx.error.code === "RATE_LIMIT_EXCEEDED") {
    await sleep(ctx.error.retryAfterMs);
    return "retry";
  }
  alerting.send(`Skill ${ctx.skill} failed: ${ctx.error.message}`);
  return "escalate";
});

El valor de retorno del gancho onError controla el comportamiento del orquestador: "retry" activa un reintento (hasta el máximo configurado), "escalate" enruta la tarea a una cola humana, "fail" finaliza la tarea inmediatamente.

Probar habilidades de forma aislada

Debido a que las habilidades tienen entradas y salidas escritas, las pruebas unitarias son sencillas. Las utilidades de prueba de OpenClaw proporcionan implementaciones simuladas de todas las interfaces de herramientas.

import { testSkill } from "@openclaw/testing";
import { ExtractLineItems } from "../skills/extract-line-items";

describe("ExtractLineItems", () => {
  it("extracts items from a valid invoice", async () => {
    const result = await testSkill(ExtractLineItems, {
      input: {
        documentUrl: "s3://test-bucket/invoice-001.pdf",
        documentType: "invoice",
      },
      mocks: {
        storage: {
          get: jest.fn().mockResolvedValue(samplePdfBuffer),
        },
      },
    });

    expect(result.lineItems).toHaveLength(3);
    expect(result.confidence).toBeGreaterThan(0.8);
  });

  it("throws DOCUMENT_NOT_FOUND for missing file", async () => {
    await expect(
      testSkill(ExtractLineItems, {
        input: { documentUrl: "s3://test-bucket/missing.pdf", documentType: "invoice" },
        mocks: { storage: { get: jest.fn().mockResolvedValue(null) } },
      })
    ).rejects.toMatchObject({ code: "DOCUMENT_NOT_FOUND" });
  });
});

Utilice el modo Sandbox para pruebas de integración. Sandbox reproduce los rastros de producción registrados con su código de habilidad actual, detectando las regresiones antes de que lleguen a los sistemas activos.

npx openclaw sandbox replay --trace=traces/invoice-20240315.json

Implementación en producción

Los agentes OpenClaw se pueden implementar como contenedores Docker, funciones sin servidor o procesos de larga duración. El patrón recomendado para implementaciones empresariales es un grupo de agentes en contenedores detrás de una cola de tareas.

FROM openclaw/runtime:node-20
WORKDIR /agent
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN npx openclaw build
CMD ["npx", "openclaw", "serve", "--workers=4"]

Para escenarios de alto rendimiento, configure el grupo de agentes con reglas de escalamiento automático. El tiempo de ejecución de OpenClaw expone las métricas de Prometheus en /metrics para la profundidad de la cola, percentiles de latencia de habilidades, tasas de error y uso de memoria; conéctelos a su pila de alertas.

Lista de verificación de producción antes de la puesta en marcha:

Todas las variables de entorno están en un administrador de secretos (AWS Secrets Manager, HashiCorp Vault), no en archivos .env.
Los backends de memoria (Redis, PostgreSQL) tienen configurada la agrupación de conexiones.
La configuración maxConcurrentTasks coincide con la capacidad de su infraestructura.
Los límites de velocidad en llamadas a herramientas externas coinciden con los límites de API del proveedor.
Se configura una cola de mensajes fallidos para tareas que agotan los reintentos.
El rastreo distribuido (OpenTelemetry) está habilitado y los rastreos fluyen hacia su plataforma de observabilidad.

Preguntas frecuentes

¿Cómo decide el orquestador de OpenClaw qué habilidad ejecutar a continuación?

El orquestador utiliza una combinación de descomposición de objetivos y combinación de habilidades. Divide el objetivo de nivel superior en subobjetivos y luego consulta el registro de habilidades utilizando similitud semántica con la descripción de cada subobjetivo. Las habilidades se clasifican según su puntuación de relevancia, disponibilidad de dependencia y tasa de éxito histórica. El orquestador crea un gráfico acíclico dirigido de ejecuciones de habilidades y resuelve dependencias antes de comenzar.

¿Puede una habilidad llamar a otra habilidad directamente?

No, las habilidades no deben llamar directamente a otras habilidades. La coordinación entre habilidades es responsabilidad del orquestador. Si necesita el resultado de la habilidad A antes de que se ejecute la habilidad B, declare la dependencia en el plan del orquestador. Esto mantiene las habilidades sin estado y comprobables individualmente. La excepción son las habilidades compuestas, que están marcadas explícitamente como primitivas de orquestación.

¿Qué sucede cuando una API externa no funciona durante la ejecución de una habilidad?

El gancho onError intercepta el error. Si el enlace devuelve "retry", el orquestador espera el intervalo de retroceso configurado y vuelve a intentar la habilidad. Después de agotadores reintentos, la tarea pasa a la cola de mensajes fallidos. Si tiene una habilidad alternativa registrada para la misma capacidad, el orquestador la probará antes de darse por vencido. El estado de la tarea parcial se conserva en la memoria de trabajo para que la tarea pueda reanudarse desde la última habilidad exitosa.

¿Cómo se manejan los secretos que las habilidades necesitan en tiempo de ejecución?

Las herramientas declaradas en el manifiesto del agente se inicializan con credenciales al inicio, no por habilidad. Su administrador de secretos completa las variables de entorno a las que se hace referencia en el manifiesto (${ERP_BASE_URL}, ${DOCS_BUCKET}, etc.) al iniciar el contenedor. Las habilidades nunca ven credenciales sin procesar: interactúan con instancias de herramientas previamente autenticadas inyectadas por el tiempo de ejecución.

¿Existe un límite en la cantidad de habilidades que puede tener un agente?

El registro de habilidades no tiene un límite estricto, pero la calidad de la orquestación práctica se degrada si registra cientos de habilidades con descripciones superpuestas. Agrupe las habilidades relacionadas en paquetes de habilidades y utilice descripciones claras y distintas. Para bibliotecas de habilidades muy grandes, considere dividirlas en agentes especializados y utilizar la orquestación de múltiples agentes para enrutar las tareas al agente adecuado.

¿Pueden los agentes OpenClaw ejecutarse localmente sin dependencias de la nube?

Sí. OpenClaw es independiente de la nube. El tiempo de ejecución, los backends de memoria y la capa de herramientas se pueden configurar para utilizar la infraestructura local. Redis puede ejecutarse localmente, el backend de memoria a largo plazo puede apuntar a una instancia de PostgreSQL local y las integraciones de herramientas pueden apuntar a API internas. La única llamada externa es al proveedor de LLM para el razonamiento del orquestador; puede configurar esto para usar un LLM local si es necesario.

¿Cómo versionas las habilidades del agente sin interrumpir las tareas en ejecución?

Las habilidades se versionan en el manifiesto del agente con versiones semánticas. El tiempo de ejecución admite la ejecución de varias versiones de habilidades simultáneamente durante una implementación continua. Las tareas en vuelo continúan usando la versión de habilidad con la que comenzaron; Las nuevas tareas recogen la última versión. Los cambios importantes en los esquemas de entrada/salida de habilidades requieren un aumento importante de la versión y un plan de migración para cualquier agente que consuma la salida de esa habilidad.

Próximos pasos

Crear agentes de IA de nivel de producción requiere más que un buen código: requiere experiencia operativa con modos de falla, patrones de escalado y bibliotecas de habilidades específicas de dominio que llevan meses desarrollar y perfeccionar.

El [servicio de habilidades personalizadas de OpenClaw] (/services/openclaw/custom-skills) de ECOSIRE proporciona desarrollo de agentes de extremo a extremo: análisis de requisitos, arquitectura de habilidades, integración con sus sistemas existentes, pruebas, implementación y optimización continua. Nuestro equipo ha creado agentes OpenClaw para procesamiento de documentos, automatización de ERP, atención al cliente, análisis financiero y más.

Hable con un especialista de OpenClaw para analizar sus requisitos de automatización y obtener una hoja de ruta de desarrollo personalizada.

Building Custom AI Agents with OpenClaw: Developer Guide