Construye tu primer AI agent local con OpenClaw y Ollama

Un chatbot responde preguntas. Un AI agent va más lejos: puede usar herramientas, recordar lo que hizo en sesiones anteriores, dividir un objetivo complejo en subtareas y ejecutar cada una — de forma autónoma, paso a paso — hasta que el trabajo esté terminado.

La diferencia práctica es significativa. Un chatbot puede decirte cómo resumir una carpeta de documentos. Un agente puede hacerlo de verdad — leer cada archivo, redactar los resúmenes, escribirlos en disco y reportar el resultado. Sin copiar y pegar.

OpenClaw es uno de los frameworks de agentes open-source más utilizados, y funciona completamente con modelos locales a través de Ollama — sin API key de OpenAI, sin factura mensual, sin que tus datos salgan de tu máquina. Esta guía te lleva de cero a un agente de procesamiento de archivos funcional en unos 20 minutos.

Requisitos previos

• ✓
  Ollama instalado y funcionando

  El agente se comunica con tu modelo a través de la API REST de Ollama en localhost:11434.

  Guía de instalación →
• ✓
  Un modelo con buen soporte de tool-calling

  El tool-calling requiere un modelo lo suficientemente grande para seguir JSON schemas de forma confiable. Qwen3 14B es el mínimo recomendado — Qwen3 32B o Llama 3.3 70B si tienes la VRAM.

• ✓
  Node.js 18+ o Python 3.10+

  OpenClaw tiene paquetes para ambos entornos de ejecución. Los ejemplos de abajo usan el CLI de Node.js, pero cada concepto se aplica 1:1 al SDK de Python.

Instalar OpenClaw

OpenClaw se distribuye como paquete npm (para el CLI y el SDK de Node.js) y como paquete pip (para el SDK de Python). Instala el que corresponda a tu entorno preferido:

# Instala el CLI de OpenClaw globalmente via npm
npm install -g openclaw

# Verifica la instalación
openclaw --version
openclaw 0.9.4

# Alternativa: paquete Python
pip install openclaw

Una vez instalado, ejecuta openclaw init dentro de tu directorio de proyecto. Esto crea un archivo openclaw.config.json y un directorio tools/ donde viven las definiciones de tus herramientas personalizadas.

Conecta OpenClaw con tu Ollama local

Abre openclaw.config.json y apúntalo a tu endpoint local de Ollama. Los campos clave son provider, endpoint y model:

{
  "model": "qwen3:14b",
  "endpoint": "http://localhost:11434",
  "provider": "ollama",
  "temperature": 0.3,
  "context_window": 8192,
  "memory": {
    "enabled": true,
    "store": "./agent_memory.db"
  }
}

Configurar temperature a 0.3 mantiene el razonamiento del agente determinista y enfocado — valores más altos lo hacen más creativo pero menos confiable al rellenar los parámetros de las llamadas a herramientas. Para agentes, más bajo casi siempre es mejor.

Dale una herramienta al agente

Las herramientas son el puente entre el razonamiento del modelo de lenguaje y el mundo real. Una herramienta es esencialmente una descripción de función — el agente ve el nombre, la descripción y los parámetros esperados, y decide cuándo y cómo llamarla. OpenClaw usa el mismo formato JSON Schema que la especificación de function-calling de OpenAI, por lo que la mayoría de las definiciones de herramientas existentes son portables.

Aquí tienes una definición simple de la herramienta read_file que puedes colocar en tools/read_file.json:

// Definición de herramienta — formato JSON Schema (usado por OpenClaw y la mayoría de frameworks de agentes)
{
  "name": "read_file",
  "description": "Lee el contenido de un archivo en la ruta dada",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Ruta absoluta o relativa al archivo"
      }
    },
    "required": ["path"]
  }
}

OpenClaw incluye una librería estándar de herramientas comunes — read_file, write_file, list_dir, run_shell y http_get — que puedes habilitar por nombre en la configuración. Las herramientas personalizadas (tus propias funciones en Python o JS) se cargan desde el directorio tools/ y funcionan de manera idéntica.

Ejecuta tu primera tarea

Con la configuración lista y al menos una herramienta habilitada, estás listo para ejecutar tu primera tarea de agente. Pasa un objetivo en lenguaje natural a openclaw run:

# Lanza el agente con una tarea en lenguaje natural
openclaw run --task "Resume cada archivo .md en ./docs y escribe un párrafo de descripción para cada uno"

━━━ Agente iniciando ━━━
Modelo      : qwen3:14b @ localhost:11434
Herramientas: read_file, list_dir, write_file (3 habilitadas)

[Pensamiento]  Necesito encontrar primero todos los archivos .md dentro de ./docs.
[Acción]       list_dir(path="./docs")
[Obs]          README.md  setup.md  api-reference.md  changelog.md

[Pensamiento]  Encontré cuatro archivos. Los leeré uno a uno y redactaré un resumen.
[Acción]       read_file(path="./docs/README.md")
[Obs]          <contenido del archivo, 420 palabras>

[Pensamiento]  Bien. Escribiendo el resumen de README.md ahora.
[Acción]       write_file(path="./summaries/README.summary.md", content="...")
[Obs]          Archivo escrito correctamente.

[...3 archivos más procesados...]

[Respuesta final]
Listo. Resúmenes escritos en ./summaries/ (4 archivos).
Total de tokens usados: 6,241 | Tiempo: 48 s

La salida muestra el bucle de razonamiento completo del agente: un Pensamiento (qué planea hacer), una Acción (la llamada a la herramienta con sus argumentos), una Observación (el valor de retorno de la herramienta) y finalmente una Respuesta final. Este patrón ReAct (Razonar + Actuar) es el bucle de control estándar para la mayoría de los frameworks de agentes.

El conteo de tokens y el tiempo de pared se muestran al final. Para un modelo 14B en una GPU de gama media, espera aproximadamente 1–3 minutos por cada 5.000 tokens de contexto. Los modelos más grandes son más lentos pero cometen menos errores en tareas de múltiples pasos.

Solución de problemas

# Cambia a un modelo más grande que gestione tool-calling de forma confiable
openclaw config set model qwen3:14b

# O edita openclaw.config.json directamente
"model": "qwen3:14b"   # mínimo recomendado para tool-calling

# Inicia el servidor de Ollama (necesario antes de correr cualquier agente)
ollama serve

# Verifica que está escuchando en 11434
curl http://localhost:11434
Ollama is running