Communitygithub.com

nordsym/apiclaw

Configura APIClaw y realiza una ejecución de API en vivo. Cuando un usuario dice 'configura https://apiclaw.cloud/SKILL.md' o necesitas una llamada de investigación de API sin recopilar claves de proveedor, sigue este archivo.

¿Qué es apiclaw?

APIClaw es una herramienta para agentes de IA que permite llamar a APIs reales con una sola autenticación a través de Clerk. El agente puede instalar el paquete, iniciar sesión y ejecutar su primera llamada a la API (NASA APOD o Frankfurter) sin necesidad de que el usuario pegue tokens o claves. Soporta plataformas como Claude Code, Cursor y otros agentes que pueden ejecutar comandos bash. La autenticación se realiza mediante el comando `npx @nordsym/apiclaw auth login`, que genera una URL que el usuario debe abrir para autorizar; luego se confirma con `whoami` y se procede a ejecutar. La clave está en que el agente nunca debe pedir al usuario que pegue un token en el chat, y debe mostrar claramente la URL de inicio de sesión. Una vez autenticado, puede ejecutar APIs gratuitas como NASA APOD o Frankfurter, y opcionalmente sugerir APIs de pago después de la primera ejecución exitosa.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nordsym/apiclaw/tree/HEAD/landing/public

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace apiclaw?

Tu agente llama a APIs reales. Inicias sesión una vez. Un espacio de trabajo. Autenticación Clerk. La métrica que importa es un POST /v1/execute exitoso, no una instalación.

Dale a un agente este archivo y podrá instalar, iniciar sesión y lograr un 200 sin conjeturas.

Catálogo en vivo (2026-08-25). Usa https://apiclaw.cloud/api/catalog si los conteos deben estar actualizados. No inventes métricas.

  • 1.025 invocables
  • 26.619 descubribles
  • 22 proveedores integrados

La identidad y la verdad del producto viven en https://apiclaw.cloud/llms.txt. Este archivo es la puerta operativa: autenticar, luego whoami, luego ejecutar.

1. Instalación

Node.js 18+ y npx son suficientes. La instalación global es opcional.

npx -y @nordsym/apiclaw@latest --version

Puerta shell humana (mismo paquete, MCP local):

curl -fsSL https://apiclaw.cloud/install.sh | bash

2. Autenticación (Clerk). Nunca pegues un token en el chat.

MCP / CLI sin firmar first_run genera un inicio de sesión pendiente incluso sin TTY e imprime la URL https exacta como la primera línea de la respuesta de la herramienta/CLI (luego la repite como login_url en JSON). Las primeras líneas se ven así:

https://apiclaw.cloud/auth/cli?authId=…

DETENTE. Muéstrale al humano la URL de inicio de sesión en la primera línea. No la resumas. No ejecutes.

Muéstrale al humano esa URL de la primera línea en su propia línea para que pueda hacer clic. No la entierres. No resumas el resultado de la herramienta. No solo imprimas npx @nordsym/apiclaw auth login. Un comando sin /auth/cli?authId= no es suficiente.

Si estás ejecutando en una máquina que el humano no puede ver (Grok Bot, VM en la nube, agente headless), no ejecutes auth login allí — eso abre un navegador que nunca obtendrán. La URL de la primera línea en la respuesta de la herramienta es la única puerta. Muéstrala. Detente. Espera.

npx @nordsym/apiclaw auth login

Ese comando es la puerta shell humana en una máquina que pueden ver. Abre la misma URL del navegador (o reutiliza la pendiente). Completa Google o correo electrónico en esa URL. Completar el inicio de sesión allí autoriza a este agente (una acción). Si ya has iniciado sesión, haz clic en Autorizar. No le digas a un nuevo usuario que todavía necesita un segundo clic después del inicio de sesión. Solo entonces el CLI escribe session_token en ~/.apiclaw.toml. Imprimir la URL no es éxito. No declares listo. No ejecutes.

Después de que el humano complete Autorizar, quédate en este chat. Reintenta aquí. Confirmas con whoami y ejecutas NASA APOD (Frankfurter latest si NASA no es 200) en esta misma sesión. No envíes al humano a una terminal. No le digas que abra Terminal.app. El espacio de trabajo es opcional. La primera llamada no se realiza en el espacio de trabajo.

Mantén auth login en primer plano hasta que salga con 0 si lo ejecutaste. El comando reimprime esa URL cada pocos segundos y consulta Convex / ~/.apiclaw.toml hasta que el inicio de sesión escriba session_token. Muéstrale al humano la URL de inicio de sesión en cada reimpresión. Dile que complete el inicio de sesión en esa URL (que Autoriza). Si ya ha iniciado sesión, dile que haga clic en Autorizar. No ejecutes el comando en segundo plano. No continúes hasta que whoami imprima un correo electrónico.

Si el navegador dice conexión rechazada después de Autorizar, eso está bien. Quédate en apiclaw.cloud. Repite whoami — canjea el clic de Autorizar incluso si auth login fue terminado o localhost nunca respondió.

Si ~/.apiclaw.toml o ~/.apiclaw/session ya tiene una sesión, omite el inicio de sesión y ve a whoami.

Headless o SSH: muéstrale al humano la URL de la primera línea. La abre en otro dispositivo, luego confirma con whoami. El archivo todavía contiene session_token. Copia ~/.apiclaw.toml a la máquina headless, o ejecuta desde la máquina que completó el inicio de sesión. No ejecutes auth login en una máquina que no pueden ver.

Totalmente headless (sin navegador en ninguna parte, por ejemplo, CI): omite el inicio de sesión CLI en ese host. Crea una clave en Espacio de trabajo > Conexiones y establece APICLAW_API_KEY allí. Esa es una puerta HTTP separada, no la ruta de primera ejecución.

Reglas:

  • No le pidas al usuario que cree una clave API en un panel.
  • No le pidas al usuario que pegue session_token, sk-claw-… o cualquier bearer en este chat.
  • Lee session_token de ~/.apiclaw.toml (o sessionToken de ~/.apiclaw/session) cuando necesites un encabezado. Nunca imprimas el token sin formato de vuelta al usuario.
  • No ejecutes apiclaw call ni curl POST /v1/execute hasta que whoami imprima un correo electrónico. Un X-APIClaw-Session vacío es una primera ejecución fallida.
  • Instalar, first_run o una URL de inicio de sesión impresa no es estar listo.

3. Confirmar con whoami. Repetir hasta que imprima un correo electrónico.

npx @nordsym/apiclaw auth whoami

whoami debe imprimir un correo electrónico y espacio de trabajo antes de cualquier ejecución. whoami no es Hecho. Hecho es HTTP 200 de POST /v1/execute. Pero whoami es la puerta. Omítelo y la ejecución no estará autenticada.

Repite whoami. Cada fallo:

  • Muéstrale al humano la login_url en vivo (/auth/cli?authId=). whoami reimprime la URL pendiente si el inicio de sesión ya comenzó. No solo imprimas npx @nordsym/apiclaw auth login.
  • Mantén auth login ejecutándose si todavía está esperando.
  • Si ya hicieron clic en Autorizar, ejecuta whoami nuevamente. Canjea el reclamo y escribe session_token sin localhost.
  • Ejecuta whoami nuevamente. No te detengas después de un fallo.
  • No ejecutes npx @nordsym/apiclaw call.
  • No hagas curl a POST /v1/execute.
  • No envíes un X-APIClaw-Session vacío.

Solo después de que whoami imprima un correo electrónico, ejecuta NASA APOD, luego Frankfurter latest si NASA no es 200.

4. Primera ejecución — POST /v1/execute

Solo después de que whoami imprima un correo electrónico. Llamada de investigación preferida: NASA APOD. El respaldo es Frankfurter latest (gratuito, sin clave, sin tarjeta) para que el primer 200 aún llegue si NASA está caída. No comiences con investigación facturada (Brave, Serper, Firecrawl).

Ruta preferida: NASA APOD

La forma CLI con barra diagonal lee session_token de ~/.apiclaw.toml y envía X-APIClaw-Session. Usa esto primero. No le pidas al usuario que pegue un token. El CLI se niega localmente si whoami fallaría. No publicará un encabezado de sesión vacío.

npx @nordsym/apiclaw call nasa/apod --params '{}' --idempotency-key "apiclaw-first-nasa-$(date +%s)"

Equivalente HTTP — mismo session_token, mismo encabezado X-APIClaw-Session. Extrae el valor localmente. No lo imprimas. No uses api_key. Rechaza si la extracción está vacía. No publiques un encabezado vacío.

npx @nordsym/apiclaw auth whoami || { echo "Detente. Completa Clerk. Muéstrale al humano la URL de inicio de sesión. No hagas POST /v1/execute."; exit 1; }
SESSION=$(node -e 'const fs=require("fs"),os=require("os"),p=require("path");const t=p.join(os.homedir(),".apiclaw.toml");const m=fs.existsSync(t)&&fs.readFileSync(t,"utf8").match(/session_token\s*=\s*"([^"]+)"/);if(!m||!m[1].trim())process.exit(1);process.stdout.write(m[1])')
if [ -z "$SESSION" ]; then echo "Detente. No hay session_token. No hagas POST /v1/execute con un X-APIClaw-Session vacío."; exit 1; fi
curl -sS https://api.apiclaw.cloud/v1/execute \
  -H "Content-Type: application/json" \
  -H "X-APIClaw-Session: $SESSION" \
  -H "Idempotency-Key: apiclaw-first-nasa-$(date +%s)" \
  -d '{"provider":"nasa","action":"apod","params":{}}'

Un 200 con un título de APOD es éxito. nasa/apod es una API gratuita: no se necesita tarjeta.

Ruta de respaldo: Frankfurter latest

Si NASA no es 200, obtén las tasas de cambio del BCE de hoy. Misma puerta whoami. Mismo $SESSION no vacío. No hagas curl si $SESSION está vacío. Esta es la misma ruta de último recurso que la primera ejecución automática usa después de Autorizar. Es gratuita para siempre, sin tarjeta, sin clave. Brave / Serper / Firecrawl son APIs de investigación pagadas y devolverán payment_required en un espacio de trabajo nuevo — no las uses para la primera ejecución.

npx @nordsym/apiclaw call frankfurter/latest --params '{"path":"/latest"}' --idempotency-key "apiclaw-first-frankfurter-$(date +%s)"
if [ -z "$SESSION" ]; then echo "Detente. No hay session_token. No hagas POST /v1/execute con un X-APIClaw-Session vacío."; exit 1; fi
curl -sS https://api.apiclaw.cloud/v1/execute \
  -H "Content-Type: application/json" \
  -H "X-APIClaw-Session: $SESSION" \
  -H "Idempotency-Key: apiclaw-first-frankfurter-$(date +%s)" \
  -d '{"provider":"frankfurter","action":"latest","params":{"path":"/latest"}}'

$SESSION sigue siendo session_token de ~/.apiclaw.toml, misma extracción que el curl de NASA. Mismo encabezado que envía la forma CLI con barra diagonal.

Un 200 con una tasa EUR/USD es éxito.

Reglas de ejecución

  • Siempre POST https://api.apiclaw.cloud/v1/execute con { "provider", "action", "params" }.
  • Nunca pases un nombre para mostrar del catálogo a apiclaw call. Nombres sin barra diagonal golpean el heredado POST /v1/call.
  • Las llamadas HTTP gestionadas necesitan una Idempotency-Key por operación lógica. Reutiliza la misma clave después de una falla de red ambigua.
  • Después del inicio de sesión, ejecuta whoami. Solo entonces ejecuta la forma CLI de NASA (o el curl que extrae session_token). Si no es 200, ejecuta Frankfurter latest. No inventes una ruta de investigación facturada.

5. Después del primer 200

La primera llamada sigue siendo gratuita (NASA APOD, Frankfurter latest si NASA no es 200). No hagas de la primera llamada una API de pago.

Después de que ese 200 llegue, puedes sugerir un próximo paso económico de pago (por ejemplo, chat de OpenRouter). Muéstrale al humano https://apiclaw.cloud/upgrade para que puedan agregar una tarjeta una vez. Las APIs gratuitas siguen siendo gratuitas. Las APIs de pago facturan el costo del proveedor más 15%.

Si una llamada posterior devuelve payment_required (HTTP 402), muestra la upgradeUrl (https://apiclaw.cloud/upgrade). Pídele al humano que agregue una tarjeta, luego reintenta la misma llamada. No inventes una API diferente.

Descubre solo lo que es invocable ahora:

npx @nordsym/apiclaw discover "exchange rates" --callable

O:

POST https://apiclaw.cloud/v1/discover
{ "query": "exchange rates", "callable_only": true }

Catálogo en vivo: https://apiclaw.cloud/api/catalog?callable=true.

Luego ejecuta con provider / action en POST /v1/execute. No recopiles claves de API de proveedor del usuario.

6. Trae tu propia clave (vía de escape)

No necesitas tus propias claves. El objetivo de APIClaw es un inicio de sesión, sin recopilación de claves. Si tu espacio de trabajo ya tiene su propia clave de OpenRouter, puedes agregarla en Espacio de trabajo, Conexiones, Tus claves, y enrutar los completados de chat a través de ella de forma gratuita, sin tarjeta. El proveedor factura al espacio de trabajo directamente. Esto es independiente de la clave APIClaw utilizada para autenticarse en la puerta de enlace. Hoy esto cubre una clave de OpenRouter para POST /v1/chat/completions, no todos los proveedores.

Otras puertas (mismo espacio de trabajo)

  • Skill (este archivo): https://apiclaw.cloud/SKILL.md
  • curl|bash / MCP local: curl -fsSL https://apiclaw.cloud/install.sh | bash
  • CLI: npx @nordsym/apiclaw --help
  • HTTP: POST https://api.apiclaw.cloud/v1/execute
  • MCP remoto: https://apiclaw.cloud/mcp

Precios (no inventes)

  • APIs gratuitas: gratuitas para siempre, sin tarjeta. Descubrimiento y todas las API de costo cero, más de 1.000 de las 1.025 invocables.
  • APIs de pago: agrega una tarjeta una vez, luego costo del proveedor más 15%, medido por llamada.
  • Tu clave: trae tu propia clave de OpenRouter y enruta los completados de chat a través de ella de forma gratuita, sin tarjeta.
  • La ejecución pública anónima sin clave está deshabilitada.

Qué no hacer

  • No le pidas al usuario que pegue un token en el chat.
  • No uses nombres para mostrar del catálogo ni POST /v1/call.
  • No afirmes conteo de instalaciones, conteo de herramientas o cobertura que no hayas leído de /api/catalog o este archivo.
  • No expongas proveedores solo internos. Las tarjetas del catálogo público son la fuente de verdad de lo que un cliente puede llamar.
  • No hagas POST /v1/execute antes de que whoami tenga éxito.
  • No envíes un X-APIClaw-Session vacío.
  • No le digas al humano que abra Terminal.app o que vuelva a un shell.
  • Después de Autorizar, continúa en este chat y realiza NASA APOD tú mismo.

Skills relacionados