Con OpenClaude puedes interactuar con modelos de inteligencia artificial directamente desde tu terminal, ejecutar código, crear archivos y automatizar tareas sin depender de interfaces web. Esta guía te lleva desde la instalación hasta tu primer proyecto funcional.

No necesitas ser experto: con conocimientos básicos de Python y algo de familiaridad con la línea de comandos, tendrás una herramienta funcional en una tarde. Lo único que requieres es una computadora, conexión a internet y disposición para aprender.

¿Qué es OpenClaude?

OpenClaude es una herramienta de código abierto (licencia MIT) que funciona como un agente de programación desde la línea de comandos. No solo responde preguntas: puede leer, crear y modificar archivos, ejecutar comandos en tu sistema y tomar decisiones sobre qué hacer a continuación.

A diferencia de usar un modelo de IA desde el navegador, OpenClaude actúa directamente sobre tu entorno de trabajo. Puede:

• Crear y editar archivos de código.
• Ejecutar programas y comandos en tu terminal.
• Buscar información dentro de tu proyecto.
• Tomar decisiones sobre los pasos necesarios para completar una tarea.
• Funcionar con más de 13 proveedores de modelos de IA.

Es un proyecto independiente, desarrollado por la comunidad, y no está afiliado a Anthropic (la empresa detrás del modelo Claude). Esto significa que puede trabajar con modelos de distintos proveedores, no solo con los de Anthropic.

Puedes consultar el código fuente y la documentación completa en su repositorio: github.com/Gitlawb/openclaude

OpenClaude como agente de código

OpenClaude no es una herramienta de chat. Es un agente de código, y esa distinción importa.

Diferencia entre una herramienta de chat y un agente

Cuando usas un modelo de IA desde una página web, el modelo solo genera texto. Tú copias ese texto, lo pegas en tu editor, lo ejecutas manualmente y revisas los resultados por tu cuenta.

Un agente de código como OpenClaude automatiza ese flujo completo:

1. Recibe tu instrucción en lenguaje natural.
2. Decide qué archivos crear o modificar.
3. Escribe el código.
4. Lo ejecuta.
5. Si encuentra errores, intenta corregirlos.
6. Te reporta el resultado.

Esto no significa que sea infalible. Siempre debes revisar lo que produce. Pero el flujo de trabajo es considerablemente más rápido que hacerlo todo de forma manual.

Capacidades específicas del agente

OpenClaude incluye herramientas integradas que le permiten trabajar de forma autónoma:

• Ejecución de comandos: puede correr programas, instalar dependencias y ejecutar pruebas.
• Manipulación de archivos: leer, crear, editar y eliminar archivos en tu proyecto.
• Búsqueda en el proyecto: localizar archivos y texto específico usando expresiones regulares.
• Búsqueda web: consultar documentación actualizada en internet sin configuración adicional (usa DuckDuckGo de forma integrada).
• Agentes secundarios: delegar subtareas a otros agentes que pueden usar modelos diferentes al principal.

Requisitos previos

Antes de instalar OpenClaude, asegúrate de contar con:

• Sistema operativo: Windows, macOS o Linux.
• Terminal: saber ejecutar comandos básicos (navegar entre carpetas, ejecutar programas).
• Conocimientos básicos de Python: para seguir el proyecto práctico (variables, funciones, bucles).
• Espacio en disco: al menos 500 MB libres.
• Conexión a internet: para instalar dependencias y usar modelos en la nube.

Si nunca has usado una terminal, busca un tutorial introductorio para tu sistema operativo antes de continuar. Esa inversión inicial te ahorrará frustración más adelante.

Instalación en 3 pasos

1. Instalar Node.js y npm

OpenClaude requiere Node.js versión 22 o superior y npm (el gestor de paquetes de Node).

• Descarga Node.js desde nodejs.org. Elige la versión LTS (soporte a largo plazo).
• Durante la instalación, asegúrate de que npm esté incluido (viene activado por defecto).
• Verifica la instalación abriendo una terminal y ejecutando:

  node -v y npm -v

  Deberías ver la versión 22 o superior para Node.

Si los comandos no se reconocen, cierra y vuelve a abrir la terminal, o reinicia tu computadora.

2. Instalar ripgrep

OpenClaude usa ripgrep internamente para buscar archivos y texto en tu proyecto. Sin esta herramienta, funciones de búsqueda no operarán.

• macOS (con Homebrew): brew install ripgrep
• Ubuntu o Debian: sudo apt install ripgrep
• Windows: winget install BurntSushi.ripgrep.MSVC

  También puedes descargarlo desde github.com/BurntSushi/ripgrep

3. Instalar OpenClaude

Ejecuta en tu terminal:

npm install -g @gitlawb/openclaude@latest

Esto instala OpenClaude de forma global en tu sistema. El proceso puede tardar unos minutos dependiendo de tu conexión.

Nota: En Linux o macOS, si obtienes un error de permisos, no uses sudo como solución. En su lugar, cambia el directorio global de paquetes de npm siguiendo la documentación oficial de npm sobre resolución de permisos.

Verificación

Ejecuta openclaude --version. Si ves información del programa, la instalación fue exitosa.

Configuración del primer proveedor

Antes de usar OpenClaude, necesitas configurar un proveedor: el servicio que conecta OpenClaude con un modelo de IA. Al instalar, el proveedor predeterminado es Gitlawb Opengateway, que ofrece acceso inicial a modelos de Anthropic.

Puedes cambiar de proveedor en cualquier momento. Abre OpenClaude y ejecuta el comando:

/provider

Esto mostrará las opciones disponibles. También puedes configurar proveedores mediante variables de entorno.

Opciones de proveedores

• GitHub Models: acceso gratuito a varios modelos usando tu cuenta de GitHub. Configura con el comando /onboard-github.
• Ollama: ejecuta modelos directamente en tu computadora, sin costo y sin necesidad de internet. Instala Ollama desde ollama.ai.
• OpenRouter: acceso a más de 100 modelos con pago por uso.
• Google AI: modelos Gemini con acceso gratuito sujeto a límites diarios.
• Anthropic: modelos Claude con cuenta de pago o periodo de prueba.

Para empezar sin costo, las mejores opciones son GitHub Models (necesitas una cuenta gratuita de GitHub) u Ollama (todo se ejecuta en tu computadora).

Primer uso: tu primera interacción

Abre tu terminal y ejecuta:

openclaude

Se abrirá la interfaz de OpenClaude. Prueba algo sencillo:

¿Qué hace el comando ls -la en Linux?

OpenClaude responderá directamente en la terminal. Ahora prueba algo que demuestre su capacidad como agente:

Crea un archivo llamado hola.py que imprima "Hola mundo" y la fecha actual.

OpenClaude no solo generará el código: creará el archivo en tu sistema. Si le pides que lo ejecute, lo hará y te mostrará el resultado. Esta es la diferencia concreta entre una herramienta de chat y un agente.

Proveedores y modelos disponibles

OpenClaude funciona como un cliente universal: el proveedor determina qué modelos puedes usar, cuánto cuestan y cuáles son sus límites. Los precios y la disponibilidad cambian con frecuencia; siempre verifica en la fuente original antes de tomar decisiones.

Tabla de proveedores compatibles

Cómo elegir proveedor

• Para empezar sin costo: GitHub Models u Ollama.
• Para privacidad: Ollama (todo se ejecuta en tu computadora, nada sale a internet).
• Para la mejor calidad en programación: Anthropic (Claude Sonnet) u OpenRouter.
• Para documentos largos o análisis extenso: Google AI (Gemini).

Modelos locales populares

Si eliges Ollama como proveedor, puedes descargar modelos que se ejecutan directamente en tu computadora. Los más comunes:

Si tu computadora tiene 16 GB de RAM o menos, empieza con modelos de 7 u 8 mil millones de parámetros. Para descargar un modelo con Ollama:

ollama pull llama3.3

Nota: Los modelos más grandes son más capaces pero requieren hardware considerable. Un modelo de 70B puede no funcionar en una computadora promedio.

Proyecto práctico: gestor de tareas automatizado

En este proyecto crearemos un gestor de tareas con Python que permite agregar, completar, visualizar y eliminar tareas con fecha de vencimiento. Todo se guarda en un archivo JSON para que persista entre ejecuciones.

Lo importante de este ejercicio no es solo el resultado final, sino observar el flujo de trabajo con un agente: tú describes lo que necesitas y OpenClaude genera, ejecuta y depura el código.

Paso 1: describir lo que necesitas

En OpenClaude, escribe la siguiente instrucción:

Crea un programa en Python para un gestor de tareas que permita: 1) agregar tareas con fecha de vencimiento en formato AAAA-MM-DD, 2) marcar tareas como completadas, 3) ver todas las tareas ordenadas por fecha, 4) eliminar tareas, 5) guardar las tareas en un archivo JSON llamado tareas.json y cargarlas al iniciar. Usa un menú interactivo en la terminal con manejo de errores para fechas inválidas.

OpenClaude creará el archivo, escribirá el código y podrá ejecutarlo para verificar que funciona. Si encuentra errores, intentará corregirlos automáticamente.

Paso 2: revisar el código generado

Es importante que siempre revises el código que produce el agente. Un resultado posible es este:

import json
import os
from datetime import datetime

ARCHIVO_TAREAS = "tareas.json"


def cargar_tareas():
    if os.path.exists(ARCHIVO_TAREAS):
        with open(ARCHIVO_TAREAS, "r", encoding="utf-8") as archivo:
            return json.load(archivo)
    return []


def guardar_tareas(tareas):
    with open(ARCHIVO_TAREAS, "w", encoding="utf-8") as archivo:
        json.dump(tareas, archivo, indent=4, ensure_ascii=False)


def mostrar_tareas(tareas):
    if not tareas:
        print("No hay tareas registradas.")
        return []
    tareas_ordenadas = sorted(tareas, key=lambda x: x["fecha"])
    for i, tarea in enumerate(tareas_ordenadas, 1):
        estado = "Completada" if tarea["completada"] else "Pendiente"
        print(f"{i}. [{estado}] {tarea['tarea']} (Vence: {tarea['fecha']})")
    return tareas_ordenadas


def agregar_tarea():
    tarea = input("Descripción de la tarea: ")
    while True:
        fecha_str = input("Fecha de vencimiento (AAAA-MM-DD): ")
        try:
            datetime.strptime(fecha_str, "%Y-%m-%d")
            break
        except ValueError:
            print("Formato inválido. Usa AAAA-MM-DD (ejemplo: 2026-12-31).")
    tareas = cargar_tareas()
    tareas.append({"tarea": tarea, "fecha": fecha_str, "completada": False})
    guardar_tareas(tareas)
    print(f"Tarea '{tarea}' agregada con fecha {fecha_str}.")


def marcar_completada():
    tareas = cargar_tareas()
    if not tareas:
        print("No hay tareas.")
        return
    ordenadas = mostrar_tareas(tareas)
    try:
        indice = int(input("Número de la tarea completada: ")) - 1
        if 0 <= indice < len(ordenadas):
            objetivo = ordenadas[indice]
            for t in tareas:
                if (t["tarea"] == objetivo["tarea"]
                        and t["fecha"] == objetivo["fecha"]):
                    t["completada"] = True
                    break
            guardar_tareas(tareas)
            print(f"Tarea '{objetivo['tarea']}' completada.")
        else:
            print("Número fuera de rango.")
    except ValueError:
        print("Debes ingresar un número.")


def eliminar_tarea():
    tareas = cargar_tareas()
    if not tareas:
        print("No hay tareas.")
        return
    ordenadas = mostrar_tareas(tareas)
    try:
        indice = int(input("Número de la tarea a eliminar: ")) - 1
        if 0 <= indice < len(ordenadas):
            objetivo = ordenadas[indice]
            tareas = [
                t for t in tareas
                if not (t["tarea"] == objetivo["tarea"]
                        and t["fecha"] == objetivo["fecha"])
            ]
            guardar_tareas(tareas)
            print(f"Tarea '{objetivo['tarea']}' eliminada.")
        else:
            print("Número fuera de rango.")
    except ValueError:
        print("Debes ingresar un número.")


def menu():
    while True:
        print("\n--- Gestor de tareas ---")
        print("1. Agregar tarea")
        print("2. Marcar tarea como completada")
        print("3. Ver tareas")
        print("4. Eliminar tarea")
        print("5. Salir")
        opcion = input("Elige una opción: ")
        if opcion == "1":
            agregar_tarea()
        elif opcion == "2":
            marcar_completada()
        elif opcion == "3":
            mostrar_tareas(cargar_tareas())
        elif opcion == "4":
            eliminar_tarea()
        elif opcion == "5":
            print("Hasta pronto.")
            break
        else:
            print("Opción no válida.")


if __name__ == "__main__":
    menu()

Este código incluye una corrección importante: al seleccionar una tarea por número, utiliza la lista ordenada para identificar cuál modificar, evitando que se afecte la tarea equivocada.

Paso 3: ejecutar y probar

Guarda el código en un archivo llamado gestor_tareas.py y ejecútalo:

python gestor_tareas.py

Prueba agregar varias tareas con diferentes fechas, marcar una como completada, ver la lista ordenada y eliminar otra. Los datos se guardan en tareas.json y persisten entre ejecuciones.

Extensiones posibles

Una vez que el gestor funcione, puedes pedirle a OpenClaude que lo amplíe:

• Base de datos: reemplaza el archivo JSON por SQLite para manejar más datos de forma eficiente.
• Notificaciones: agrega un sistema que avise por correo cuando una tarea está próxima a vencer.
• Exportación: permite exportar las tareas a un archivo CSV o una hoja de cálculo.

En cada caso, describe lo que necesitas a OpenClaude y deja que el agente genere el código.

Ejecución en segundo plano

OpenClaude puede ejecutar instrucciones en segundo plano, lo que te permite seguir trabajando en la terminal mientras el agente procesa una tarea compleja.

Para usarlo, añade --bg al ejecutar OpenClaude:

openclaude --bg "Revisa todos los archivos Python en este proyecto y agrega docstrings a cada función"

El agente trabajará sin bloquear tu terminal. Es ideal para tareas extensas como refactorizaciones, generación de documentación o análisis de código con muchos archivos.

Integración con editores de código

OpenClaude ofrece una extensión para Visual Studio Code que integra el agente directamente en tu editor. Esto te permite generar, modificar y depurar código sin cambiar de ventana.

Busca “OpenClaude” en el marketplace de extensiones de VS Code o consulta la documentación del proyecto en GitHub para instrucciones detalladas.

Búsqueda web integrada

OpenClaude incluye herramientas de búsqueda web que le permiten consultar documentación actualizada por sí mismo:

• WebSearch: busca en internet usando DuckDuckGo de forma integrada, sin configuración adicional ni costos.
• WebFetch: descarga y lee el contenido de páginas web específicas que le indiques.

Esto es útil cuando trabajas con tecnologías que cambian rápido: el agente puede consultar la documentación más reciente en lugar de depender únicamente de su conocimiento entrenado.

Seguridad al usar OpenClaude

OpenClaude es un agente que ejecuta código y comandos en tu sistema. Esto lo hace poderoso, pero también requiere precaución.

Lo que OpenClaude puede hacer en tu computadora

• Crear, modificar y eliminar archivos.
• Ejecutar comandos en la terminal.
• Instalar dependencias de software.
• Acceder a archivos dentro del directorio de trabajo.

Prácticas de seguridad recomendadas

1. Revisa antes de confirmar. OpenClaude pedirá confirmación antes de ejecutar comandos destructivos. Lee lo que va a hacer antes de aceptar.
2. Trabaja en un directorio aislado. Ejecuta OpenClaude en una carpeta específica para tus proyectos, no en tu directorio personal o en la raíz del sistema.
3. No incluyas información sensible en tus instrucciones. Si usas modelos en la nube, evita incluir contraseñas, claves de acceso o datos personales.
4. Usa modelos locales para código confidencial. Con Ollama, todo se procesa en tu computadora y nada se envía a servidores externos.
5. Verifica las dependencias. Si el agente instala paquetes, revisa cuáles son antes de continuar.
6. Mantén copias de seguridad. Antes de tareas grandes de refactorización, asegúrate de tener tu código respaldado, por ejemplo con Git.

Consejos para principiantes

Indicaciones efectivas

La calidad del resultado depende directamente de lo que le pidas al agente:

• Sé específico. En lugar de “ayúdame con Python”, prueba “crea una función en Python que reciba una lista de números y devuelva solo los pares, ordenados de menor a mayor”.
• Describe el resultado esperado. “El programa debe crear un archivo CSV con columnas de nombre y correo” es mejor que “procesa estos datos”.
• Menciona restricciones. Si necesitas una librería específica, compatibilidad con Python 3.10 o que no se instalen dependencias adicionales, dilo en la instrucción.
• Divide tareas complejas. Si tu proyecto tiene varias partes, abórdalas una a la vez en lugar de pedir todo junto.
• Guarda tus instrucciones más útiles. Crea un archivo de texto con las instrucciones que mejores resultados te den. Así no tendrás que escribirlas de nuevo.

Errores comunes

• Usar Node.js 18: OpenClaude requiere la versión 22 o superior. Verifica con node -v.
• No instalar ripgrep: sin esta herramienta, la búsqueda de archivos en tu proyecto no funcionará.
• No revisar el código generado: el agente puede cometer errores o tomar decisiones inesperadas. Siempre lee lo que produce antes de ejecutarlo en un proyecto importante.
• Esperar resultados perfectos a la primera: a veces el agente necesita varias iteraciones. Si el primer resultado no es correcto, dale instrucciones más detalladas o señálale qué falló.
• Usar modelos grandes sin hardware suficiente: un modelo de 70B necesita decenas de gigabytes de RAM. Empieza con modelos de 7 u 8B si tu computadora tiene recursos limitados.
• Olvidar guardar el código: si generas código desde la terminal, guárdalo en un archivo antes de cerrar la sesión.

Conclusión

Con esta guía tienes lo necesario para empezar a usar OpenClaude de manera productiva. Has aprendido a:

• Instalar y configurar OpenClaude con sus dependencias.
• Entender qué es un agente de código y cómo se diferencia de una herramienta de chat.
• Configurar proveedores gratuitos y de pago.
• Crear una herramienta funcional usando el agente.
• Ejecutar tareas en segundo plano.
• Aplicar prácticas de seguridad adecuadas.

El siguiente paso es usar OpenClaude para resolver un problema concreto que tengas: automatizar un reporte, generar documentación para un proyecto, crear un programa que procese datos. Empieza con algo pequeño, revisa lo que el agente produce, y aumenta la complejidad conforme te sientas cómodo con la herramienta.