Integración de APIs Externas en OpenClaw Skills: Guía Detallada para Principiantes

Hemos cubierto el desarrollo básico y la expansión de funcionalidades de OpenClaw Skills. Muchos usuarios preguntan cómo hacer que sus Skills llamen a APIs externas o cómo configurar claves de API. La respuesta es sorprendentemente simple: llamar a una API desde un Skill se reduce a realizar una solicitud de red en un script de Python. No necesitas entender principios complejos de APIs ni escribir código avanzado. Dominando una plantilla universal, puedes integrar fácilmente cuaqluier API de terceros (gratuita, con clave o desarrollada por ti mismo), duplicando la funcionalidad de tu Skill.

Esta guía, amigable para principiantes, cubre desde los principios fundamentales hasta casos prácticos, desde APIs gratuitas hasta interfaces que requieren claves. Es un tutorial paso a paso que incluso aquellos sin experiencia previa en codificación pueden seguir para obtener resultados.

1. Entendiendo la Llamada a APIs en Skills

En términos sencillos, una API es una "interfaz de funcionalidad preconstruida". Por ejemplo, consultar el clima, obtener texto para redes sociales, ver tendencias o rastrear paquetes. En lugar de desarrollar estas funciones desde cero, puedes obtener datos directamente llamando a una API existente. El Skill de OpenClaw actúa como un "puente", transformando la funcionalidad de la API en una herramienta que la IA puede utilizar. Esencialmente, un Skill que llama a una API permite a la IA usar tu script para "preguntar" a la API por datos y luego procesar esa información para devolvértela.

Nuestro Skill de consulta meteorológica anterior, por ejemplo, utilizaba una API meteorológica gratuita. Hoy, crearemos un caso de uso más simple: llamar a la API "Hitokoto" para obtener una frase aleatoria, sin operaciones complejas, para que comprendas la lógica central.

2. Preparación Esencial: 3 Pasos Sencillos

Antes de comenzar, solo necesitas realizar tres acciones. No se requieren herramientas complejas adicionales; solo necesitas una computadora y OpenClaw:

Instalar la biblioteca requests: Esta es la herramienta principal para realizar solicitudes de red. Abre tu terminal e introduce el siguiente comando. Solo necesitas instalarla una vez, y luego podrás usarla para todas las llamadas a la API: pip install requests
Encontrar una interfaz de API: Para principiantes, se recomiendan APIs públicas y gratuitas que no requieran claves para evitar problemas.
Preparar la estructura básica del Skill: Utiliza la estructura familiar de SKILL.md y la carpeta scripts/. No necesitas crear archivos adicionales.

Aquí tienes algunas APIs públicas y gratuitas recomendadas para principiantes (accesibles directamente sin necesidad de claves) que puedes usar para probar:

API Hitokoto: https://v1.hitokoto.cn/ (Devuelve frases y citas aleatorias).
API Meteorológica: https://cn.apihz.cn/api/tianqi/tqybip.php

3. Caso Práctico: Desarrollando un Skill de Frases Aleatorias (Llamando a la API Hitokoto)

Usaremos la API Hitokoto como ejemplo para desarrollar un Skill que devuelva frases aleatorias. Este proceso consta de 4 pasos. Cada paso incluye código listo para usar, así que simplemente copia y pega. Se recomienda seguir los pasos mientras lees para una mejor comprensión.

Paso 1: Crear el Directorio del Skill (Estrcutura Estándar)

Al igual que al desarrollar Skills anteriores, primero crea una carpeta para el Skill dentro de tu directorio de proyecto de OpenClaw. Nómbrala quote-skill (el nombre es personalizable, se prefieren los nombres en inglés). Luego, crea la siguiente estructura:

quote-skill/
├─ SKILL.md           # Archivo de configuración del Skill (para que la IA lo reconozca)
└─ scripts/
   └─ quote.py        # Script principal (lógica para llamar a la API)

Esta estructura es idéntica a la de hello-skill y weather-skill. Los principiantes no necesitan memorizar nuevas reglas; pueden seguir la lógica anterior.

Paso 2: Escribir SKILL.md (Instruyendo a la IA)

SKILL.md funciona como el "manual de instrucciones" del Skill. Le indica a la IA qué es el Skill, cuándo usarlo y qué parámetros necesita. Dado que la API Hitokoto no requiere parámetros, args se deja vacío. Copia y pega el siguiente contenido:

---
name: quote-skill
description: Obtiene una frase aleatoria, cita inspiradora o cita corta sin necesidad de parámetros.
version: 1.0.0
author: Tu Nombre
type: script
scope: local
command: python3 scripts/quote.py
args: []  # No requiere parámetros, se deja vacío.
---

# Instrucciones de Uso del Skill
Cuando el usuario necesite una frase aleatoria, una cita inspiradora, una cita corta, o una frase reconfortante, este Skill se llamará automáticamente. No se requieren parámetros; la llamada directa devolverá el resultado.

Nota importante: Si tu API requiere parámetros (por ejemplo, la API meteorológica requiere el nombre de la ciudad), agrégalos en args, de forma similar a como lo hicimos en el Skill meteorológico. Explicaremos esto en detalle más adelante.

Paso 3: Escribir quote.py (El Código Central para Llamar a la API)

Este es el paso crucial, pero el código es extremadamente simple. Sigue la "plantilla universal", solo necesitas reemplazar la URL de la API y la lógica de extracción de datos. Copia el siguiente código y pégalo en scripts/quote.py. Explicaremos cada línea para que entiendas el propósito de cada paso:

import requests  # Importa la biblioteca para realizar solicitudes de red (la que instalaste antes)

# 1. Define la URL de la API a llamar (API Hitokoto, gratuita y pública, no requiere clave)
api_url = "https://v1.hitokoto.cn/"

try:
    # 2. Realiza una solicitud GET para llamar a la API (timeout=10 significa un tiempo de espera de 10 segundos para evitar bloqueos)
    response = requests.get(api_url, timeout=10)
    
    # 3. Convierte el resultado devuelto por la API a formato JSON (facilita la extracción de datos)
    data = response.json()
    
    # 4. Extrae la información que necesitamos de los datos JSON (el texto de la frase y su origen)
    # Puedes imprimir 'data' primero para ver todos los datos devueltos por la API y luego extraer los campos correspondientes.
    quote_content = data["hitokoto"]  # Contenido de la frase
    quote_source = data["from"]       # Origen de la frase
    
    # 5. Imprime el resultado (debe ser con 'print' para que la IA pueda leerlo y devolverlo al usuario)
    print(f"📝 Frase Aleatoria: {quote_content}")
    print(f"✍️ Origen: {quote_source}")

# Captura excepciones (evita que el Skill colapse debido a inestabilidad de la red o fallos de la API)
except Exception as e:
    print(f"Error al llamar a la API: {str(e)}")

Explicación línea por línea (¡Imprescindible para principiantes!):

import requests: Importa la biblioteca que instalamos previamente. Sin ella, no puedes realizar solicitudes de red.
api_url: Es la dirección de la API que queremos llamar. Si usas otra API, solo necesitas cambiar esta línea.
requests.get(): Realiza una solicitud GET (el método de solicitud más común para consultar datos).
response.json(): Convierte el contenido devuelto por la API a formato JSON, similar a un "diccionario ordenado", lo que facilita la extracción de los datos deseados.
print(): Es obligatorio imprimir el resultado para que la IA pueda leerlo y devolverlo al usuario. ¡No te saltes este paso!
try...except: Captura errores. Si la red es inestable o la dirección de la API es incorrecta, se mostrará un mensaje de error en lugar de que el Skill colapse directamente. Los principiantes deben incluir esto.

Paso 4: Desplegar y Probar el Skill (30 Segundos)

El método de despliegue es idéntico al de los Skills anteriores. No se requiere ninguna operación adicional:

Mueve la carpeta quote-skill a la carpeta skills dentro de tu directorio de proyecto de OpenClaw (créala si no existe).
Reinicia tu sesión de OpenClaw (cierra y vuelve a abrir).
Prueba la llamada: Introduce "Dame una frase aleatoria". La IA llamará automáticamente a quote-skill y devolverá un resultado similar a este: ```

📝 Frase Aleatoria: La vida no tiene caminos equivocados, cada paso cuenta. ✍️ Origen: Desconocido

¡Felicidades! Has integrado con éxito una API de terceros en tu Skill. ¿No fue increíblemente simple? La primera vez que lo logré, probé varias llamadas solo para ver aparecer diferentes frases, ¡fue muy gratificante!

4. Avanzado: ¿Qué Hacer si la API Requiere una Clave (API Key)?

Hemos utilizado una API gratuita que no requiere clave. Sin embargo, la mayoría de las APIs prácticas (como las de mapas de Amap, Baidu AI, OpenWeatherMap) requieren una API Key para la autenticación y para evitar el uso indebido. La implementación es similar a la de las APIs gratuitas, solo se añade un paso para "pasar la clave". Aquí tienes una plantilla estándar (puedes copiarla y usarla) usando la API de OpenWeatherMap como ejemplo:

import requests

# 1. Configura la clave de API y los parámetros
API_KEY = "TU_CLAVE_DE_API"  # Reemplaza con tu clave
city = "Beijing"           # Ciudad a consultar

# 2. URL de la API (con marcadores de posición para parámetros)
api_url = "https://api.openweathermap.org/data/2.5/weather"

# 3. Pasa los parámetros (incluye la clave y el nombre de la ciudad)
params = {
    "q": city,          # Parámetro de ciudad
    "appid": API_KEY,   # Parámetro de clave
    "lang": "zh_cn",    # Retorno en chino
    "units": "metric"   # Grados Celsius
}

try:
    response = requests.get(api_url, params=params, timeout=10)
    data = response.json()
    # Extrae e imprime los datos (ajusta según los campos devueltos por la API)
    print(f"🌤️ Clima en tiempo real de {city}: {data['weather'][0]['description']}")
    print(f"Temperatura: {data['main']['temp']}℃")
except Exception as e:
    print(f"Fallo en la llamada: {str(e)}")

Recordatorio importante: Guarda tu API Key de forma segura y no la expongas. Es mejor no escribirla directamente en el script (puedes usar variables de entorno para esto, pero para principiantes, escribirla directamente está bien por ahora, se optimizará más adelante).

5. Tres Formas Comunes de Llamar a APIs en Skills (Domínalas Todas para Cualquier Escenario)

Dependiendo de la API, podrías necesitar diferentes métodos de solicitud. Aquí resumimos las 3 formas más comunes, cubriendo el 99% de los escenarios. Si los principiantes recuerdan estas tres formas, podrán manejar cualquier API:

1. Solicitudes GET (Más Común)

Escenarios de uso: Consultar datos (clima, frases, tendencias, paquetes). Los parámetros se concatenan directamente en la URL o se pasan a través de params, como en los dos ejemplos anteriores:

# Método 1: Parámetros concatenados en la URL
requests.get("https://api.ejemplo.com/clima?ciudad=Beijing")

# Método 2: Pasar parámetros con 'params' (más estándar, recomendado)
parametros = {"ciudad": "Beijing"}
requests.get("https://api.ejemplo.com/clima", params=parametros)

2. Solicitudes POST (Envío de Datos)

Escenarios de uso: Enviar datos (como enviar mensajes, enviar formularios). Los parámetros se colocan en el cuerpo de la solicitud. Uso:

import requests

url = "https://api-ejemplo.com/enviar"
datos = {"nombre": "Juan", "contenido": "Contenido de prueba"}  # Datos a enviar

# Realiza una solicitud POST, pasando datos en formato JSON
respuesta = requests.post(url, json=datos, timeout=10)
print(respuesta.json())

3. Token/Clave en Encabezados de Solicitud (Avanzado)

Escenarios de uso: Algunas APIs requieren que la clave se incluya en los encabezados de la solicitud en lugar de como parámetro. Uso:

import requests

url = "https://api-ejemplo.com/datos"
encabezados = {
    "Authorization": "Bearer TU_TOKEN",  # Reemplaza con tu Token/Clave
    "Content-Type": "application/json"
}

respuesta = requests.get(url, headers=encabezados, timeout=10)
print(respuesta.json())

6. Puntos Clave para Principiantes: 4 Errores Comunes a Evitar (¡No Cometas Mis Errores!)

Olvidar instalar la biblioteca requests: Al llamar a la API, se producirá un error como "no module named requests". Solución: Ejecuta pip install requests en la terminal y vuelve a intentarlo.
Dirección de API incorrecta: Asegúrate de copiar la URL completa de la API, prestando atención a las diferencias entre http y https. Una dirección incorrecta provocará un "Fallo en la solicitud".
No capturar excepciones: Si la red es inestable o la API falla, el Skill colapsará directamente. Asegúrate de incluir try...except para mostrar mensajes de error más amigables.
Olvidar imprimir el resultado: La IA no puede leer el valor de retorno del script. Incluso si la llamada a la API tiene éxito, no se devolverá al usuario. ¡Este es el error más común entre los principiantes!

7. Resumen: Llamar a APIs en Skills es Esencialmente un "Proceso de 3 Pasos"

Independientemente de si se trata de una API gratuita, una API con clave o diferentes métodos de solicitud, la lógica central es la misma. En resumen, son 3 pasos:

Importa la biblioteca requests, prepara la URL de la API y los parámetros (incluida la clave).
Realiza la solicitud y obtén los datos devueltos por la API.
Extrae los datos necesarios e imprímelos con print para que la IA pueda leerlos.

Además, un solo Skill puede llamar a múltiples APIs. Por ejemplo, puedes crear un "Skill de Herramienta Universal" que llame simultáneamente a las APIs de clima, frases y chistes. Solo necesitas añadir múltiples funciones en el script y usar parámetros para controlar el cambio de funcionalidad, lo cual es exactamente lo mismo que discutimos en la expansión de funcionalidades de Skills.

Etiquetas: OpenClaw Skills API Python requests

Publicado el 8-5 15:46

Friki Work