Tutorial para la instalación de OpenFang

Dificultad: Nivel principiante | Tiempo: 15 minutos | Logros: Dominar la implementación de OpenFang y la configuración de modelos

Introducción

Si estás buscando un framework de AI Agent ligero y potente, OpenFang merece tu atención. Se trata de un Sistema Operativo para Agents de código abierto escrito en Rust. Todo el sistema compilado ocupa solo unos 32MB, pero incluye soporte nativo para más de 20 proveedores de LLM, incluidos Anthropic Claude, Google Gemini, OpenAI GPT, DeepSeek, Groq y más.

A diferencia de los frameworks tradicionales, OpenFang no es un simple envoltorio para Chatbots, sino un verdadero sistema de Agents autónomos que pueden trabajar por ti: pueden ejecutarse según un horario programado, ayudarte a construir grafos de conocimiento, monitorear objetivos, generar leads, gestionar redes sociales y reportar automáticamente los resultados a tu Dashboard.

Hoy vamos a construirlo juntos.

Audiencia Objetivo

Desarrolladores con 1 a 5 años de experiencia
Personal técnico interesado en AI Agents
Entusiastas de la tecnología que desean desplegar capacidades de IA locales rápidamente

Dependencias y Entorno Principal

Antes de comenzar, asegúrate de que tu máquina cumpla con los siguientes requisitos:

Sistema Operativo: Linux, macOS, Windows (WSL2 o PowerShell)
Rust: 1.75+ (se recomienda usar rustup para la gestión)
Memoria: Al menos 4GB de RAM
Disco: Al menos 500MB de espacio disponible

Instalar Rust (si aún no lo tienes)

# Linux/macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows (usando PowerShell)
irm https://sh.rustup.rs | iex

Una vez finalizada la instalación, ejecuta rustc --version para confirmar la versión.

Estructura del Proyecto

openfang/
├── agents/                 # Directorio de plantillas de Agents
│   ├── hello-world/
│   ├── coder/
│   ├── researcher/
│   └── ...
├── crates/                # Rust crates (14 en total)
│   ├── openfang-cli/      # Línea de comandos CLI
│   ├── openfang-runtime/  # Núcleo del tiempo de ejecución
│   ├── openfang-api/      # API REST
│   └── ...
├── docs/                  # Documentación oficial
├── sdk/                   # SDK multi-lenguaje
│   ├── python/
│   └── javascript/
└── config.toml.example    # Ejemplo de configuración

Instalación Rápida

Opción 1: Instalación oficial en un solo paso (Recomendado)

Linux/macOS:

curl -fsSL https://openfang.sh/install | sh

Windows PowerShell:

irm https://openfang.sh/install.ps1 | iex

Al terminar, verás el siguiente mensaje:

✅ OpenFang installed successfully!
Run 'openfang init' to get started.

Opción 2: Compilación manual

Si prefieres construir desde el código fuente o estás en un entorno que no soporta la instalación automática:

# Clonar el repositorio
git clone https://github.com/RightNow-AI/openfang.git
cd openfang

# Compilar la versión release
cargo build --release

# O compilar solo el CLI
cargo build --release -p openfang-cli

Tras la compilación, el archivo binario se encontrará en target/release/openfang (o target/release/openfang.exe).

Configuración Inicial

Crear el archivo de configuración

Ejecuta el comando de inicialización:

openfang init

Esto creará una carpeta de configuración en tu directorio personal:

~/.openfang/
└── config.toml    # Archivo de configuración principal

Estructura del archivo de configuración

Abre ~/.openfang/config.toml, la configuración básica es la siguiente:

# Configuración del servicio API
host = "127.0.0.1"
port = 4200

# API Key (opcional, se recomienda para producción)
api_key = ""

# Configuración del modelo por defecto
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"

# Configuración por defecto de los Agents
[agents.defaults]

[!TIP]
Todos los campos del archivo de configuración son opcionales; los campos omitidos utilizarán valores por defecto.

Configurar las API Keys

OpenFang permite configurar las API Keys mediante variables de entorno. Recomendamos usar Groq (cuota gratuita) o Defapi (a mitad de precio) para la primera experiencia:

# Opción 1: Groq (Gratis, con límites de velocidad)
export GROQ_API_KEY="gsk_tu_clave_Groq"

# Opción 2: Defapi (Mitad de precio, recomendado)
export DEFAPI_API_KEY="tu_clave_Defapi"

[!WARNING]
No escribas las API Keys directamente en el archivo de configuración; utiliza referencias a variables de entorno.

Iniciar el Servicio

Iniciar OpenFang

openfang start

Verás una salida similar a esta:

🚀 Starting OpenFang daemon...
📡 Server listening on http://127.0.0.1:4200
🌐 Dashboard: http://127.0.0.1:4200
✅ OpenFang is ready!

Verificar el servicio

# Comprobación de salud (Health check)
curl http://127.0.0.1:4200/api/health

# Ver modelos disponibles
curl http://127.0.0.1:4200/api/models

# Ver estado de los proveedores
curl http://127.0.0.1:4200/api/providers

Acceder al Dashboard

Abre tu navegador y visita http://127.0.0.1:4200 para ver el Web Dashboard de OpenFang.

Tu primer Agent

Crear usando una plantilla incorporada

OpenFang ofrece varias plantillas de Agents integradas en el directorio agents/:

# Listar plantillas disponibles
openfang template list

Plantillas comunes:

hello-world: El Agent de conversación más sencillo
coder: Asistente de programación
researcher: Asistente de investigación
assistant: Asistente de propósito general

Crear el Agent

# Crear usando la plantilla hello-world
openfang agent create hello-world my-first-agent

Prueba de envío de mensajes

# Enviar mensaje a través del CLI
openfang agent message my-first-agent "Hello, say hi in 3 words"

O a través de la API REST:

curl -X POST http://127.0.0.1:4200/api/agents/{agent-id}/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, say hi in 3 words"}'

Si recibes una respuesta normal, ¡significa que tu Agent ya está funcionando!

Práctica de Configuración de Modelos

Configurar Groq (Cuota gratuita)

Groq ofrece un nivel gratuito extremadamente rápido, ideal para desarrollo y pruebas:

# ~/.openfang/config.toml
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"

Variable de entorno:

export GROQ_API_KEY="gsk_tu_clave"

[!TIP]
El nivel gratuito de Groq tiene límites de velocidad. Para entornos de producción se recomienda usar otros proveedores.

Configurar Defapi (Recomendación a mitad de precio)

Si quieres usar modelos de alta calidad a un precio menor, Defapi es una excelente opción. El precio es solo el 50% del oficial:

Gemini 2.5 Pro: Oficial $1.25/M → Defapi solo $0.625/M
Claude Sonnet 4: Oficial $3.00/M → Defapi solo $1.50/M

# ~/.openfang/config.toml

# Añadir proveedor personalizado
[[providers]]
name = "defapi"
base_url = "https://api.defapi.org/v1"
api_key_env = "DEFAPI_API_KEY"

# Configurar modelo por defecto
[default_model]
provider = "defapi"
model = "claude-sonnet-4-20250514"

Variable de entorno:

export DEFAPI_API_KEY="tu_clave_Defapi"

[!TIP]
Defapi soporta múltiples protocolos: v1/chat/completions, v1/messages, v1beta/models/*, siendo perfectamente compatible con OpenFang.

Configurar Anthropic Claude

[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

export ANTHROPIC_API_KEY="sk-ant-tu_clave"

Configurar Google Gemini

[default_model]
provider = "gemini"
model = "gemini-2.5-flash"

# Tanto GEMINI_API_KEY como GOOGLE_API_KEY funcionan
export GEMINI_API_KEY="AIza_tu_clave"

Configurar OpenAI

[default_model]
provider = "openai"
model = "gpt-4o-mini"

export OPENAI_API_KEY="sk-tu_clave"

Resolución de Problemas Comunes

Q1: La API Key no parece surtir efecto

Pasos de verificación:

Confirma que la variable de entorno se exportó correctamente: echo $GROQ_API_KEY
Reinicia el servicio OpenFang: openfang restart
Revisa el estado del proveedor: curl http://127.0.0.1:4200/api/providers

Q2: El modelo aparece como no disponible

Causas posibles:

API Key no configurada o con formato incorrecto
El modelo no está en la lista de soporte del proveedor
Problemas de conexión de red

Solución:

# Ver la lista detallada de modelos
curl http://127.0.0.1:4200/api/models | jq

# Probar la conexión con un proveedor específico
curl -X POST http://127.0.0.1:4200/api/providers/groq/test

Q3: El puerto 4200 está ocupado

# Ver proceso que lo ocupa
lsof -i :4200   # Linux/macOS
netstat -ano | findstr :4200  # Windows

# Modificar el archivo de configuración para usar otro puerto
# ~/.openfang/config.toml
port = 4201

Q4: Error de compilación

Asegúrate de que la versión de Rust sea lo suficientemente reciente:

rustup update
rustc --version  # Debe ser >= 1.75

Si encuentras problemas de dependencias, intenta:

cargo clean
cargo build --release

Q5: No se encuentra el comando en Windows

Asegúrate de que el binario de OpenFang esté en el PATH:

# Añadir el directorio bin al PATH (permanente)
$env:PATH += ";$env:USERPROFILE\.openfang\bin"

# O usar la ruta completa directamente
~\.openfang\bin\openfang.exe start

Q6: Cómo ver los logs

# Ver logs en tiempo real
openfang logs

# O ver el archivo de log
cat ~/.openfang/logs/openfang.log

Direcciones Avanzadas

Hands: 7 Paquetes de Capacidades Integrados

La característica más distintiva de OpenFang son sus 7 Hands (manos) integradas:

Hand	Función
Clip	Descarga de videos de YouTube, edición, doblaje, publicación automática en redes sociales
Lead	Generación diaria de leads, prospección de clientes, calificación, eliminación de duplicados
Collector	Recolección de inteligencia OSINT, detección de cambios, construcción de grafos de conocimiento
Predictor	Motor de predicción, intervalos de confianza, seguimiento de precisión
Researcher	Investigación profunda, validación cruzada de múltiples fuentes, informes en formato APA
Twitter	Tuits automáticos, respuestas interactivas, programación de publicaciones
Browser	Automatización web, llenado de formularios, flujos de trabajo de varios pasos

# Activar Researcher Hand
openfang hand activate researcher

# Ver estado
openfang hand status researcher

# Pausar
openfang hand pause researcher

Desarrollo de Agents Personalizados

Crear un Agent personalizado:

# my-agent.toml
name = "my-agent"
version = "0.1.0"
description = "My custom agent"
author = "tu"

[model]
provider = "groq"
model = "llama-3.3-70b-versatile"

[capabilities]
tools = ["file_read", "web_fetch", "bash"]
memory_read = ["*"]
memory_write = ["self.*"]

# Desplegar Agent personalizado
openfang agent deploy my-agent.toml

Integración MCP

OpenFang soporta MCP (Model Context Protocol), que permite conectar varios servicios externos:

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

Resumen

Hoy hemos completado el proceso de implementación de OpenFang:

✅ Instalación de OpenFang (script oficial o compilación manual)
✅ Configuración inicial (config.toml + variables de entorno)
✅ Inicio y verificación del servicio
✅ Creación y prueba del primer Agent
✅ Configuración de múltiples proveedores de LLM (Groq, Defapi, Claude, Gemini)
✅ Resolución de problemas comunes

¡Ahora tienes una plataforma completa de ejecución de AI Agents! Lo siguiente que puedes intentar es:

Activar una Hand para experimentar la capacidad de trabajo automatizado.
Crear un Agent personalizado definiendo tus propias herramientas y capacidades.
Explorar la integración MCP para conectar más servicios externos.

¡Diviértete!

[!TIP]
Para entornos de producción, se recomienda usar Defapi (mitad de precio) o configurar múltiples proveedores para implementar failover y garantizar la estabilidad del servicio.