Communitygithub.com

nordsym/apiclaw

Configure APIClaw e execute uma chamada de API real. Quando um usuário disser "configure https://apiclaw.cloud/SKILL.md" ou você precisar de uma chamada de API de pesquisa sem coletar chaves de provedor, siga este arquivo. A autenticação é feita via Clerk com `npx @nordsym/apiclaw auth login`. Confirme com `npx @nordsym/apiclaw auth whoami` antes de qualquer execução. A execução é POST /v1/execute com provider/action. Nunca peça para o usuário colar um token no chat. Nunca passe um nome de exibição do catálogo para `apiclaw call`.

O que é apiclaw?

APIClaw é uma skill para agentes de IA (como Claude Code, Cursor, Codex) que permite chamar APIs reais com uma única autenticação via Clerk. O agente instala o CLI, inicia o login, mostra ao humano uma URL para autorização, confirma a identidade com `whoami` e executa uma chamada de API real (como NASA APOD ou Frankfurter) retornando um status HTTP 200. A skill suporta ambientes headless e SSH, nunca pede tokens no chat, e usa `session_token` do arquivo `~/.apiclaw.toml`. Após o primeiro sucesso gratuito, pode sugerir APIs pagas com upgrade opcional. O catálogo contém mais de 1.025 APIs chamáveis e 22 provedores integrados.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que apiclaw faz?

Seu agente chama APIs reais. Você faz login uma vez. Um workspace. Autenticação Clerk. A métrica que importa é um POST /v1/execute bem-sucedido, não uma instalação.

Dê este arquivo a um agente e ele poderá instalar, fazer login e obter um 200 sem precisar adivinhar.

Catálogo atual (2026-08-25). Use https://apiclaw.cloud/api/catalog se as contagens precisarem estar atualizadas. Não invente métricas.

  • 1.025 chamáveis
  • 26.619 descobríveis
  • 22 provedores integrados

Identidade e informações do produto estão em https://apiclaw.cloud/llms.txt. Este arquivo é a porta operacional: autenticação, depois whoami, depois execução.

1. Instalação

Node.js 18+ e npx são suficientes. Uma instalação global é opcional.

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

Porta de shell humano (mesmo pacote, MCP local):

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

2. Autenticação (Clerk). Nunca cole um token no chat.

O MCP / CLI sem assinatura first_run gera um login pendente mesmo sem TTY e imprime a URL https exata como a primeira linha da resposta da ferramenta/CLI (em seguida, repete como login_url em JSON). As primeiras linhas são:

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

PARE. Mostre ao humano a URL de login na primeira linha. Não a resuma. Não execute.

Mostre ao humano aquela URL de primeira linha em sua própria linha para que ele possa clicar. Não a enterre. Não resuma o resultado da ferramenta. Não imprima apenas npx @nordsym/apiclaw auth login. Um comando sem /auth/cli?authId= não é suficiente.

Se você estiver executando em uma máquina que o humano não pode ver (Grok Bot, nuvem VM, agente headless), não execute auth login lá — isso abre um navegador que eles nunca verão. A URL de primeira linha na resposta da ferramenta é a única porta. Mostre-a. Pare. Espere.

npx @nordsym/apiclaw auth login

Esse comando é a porta de shell humano em uma máquina que eles podem ver. Ele abre a mesma URL do navegador (ou reutiliza a pendente). Conclua o Google ou e-mail nessa URL. Completar o login lá Autoriza este agente (uma ação). Se você já estiver logado, clique em Autorizar. Não diga a um novo usuário que eles ainda precisam de um segundo clique após o login. Só então o CLI escreve session_token em ~/.apiclaw.toml. Imprimir a URL não é sucesso. Não declare pronto. Não execute.

Após o humano concluir a Autorização, permaneça neste chat. Tente novamente aqui. Você confirma com whoami e executa NASA APOD (Frankfurter latest se NASA não retornar 200) nesta mesma sessão. Não envie o humano para um terminal. Não diga a eles para abrir Terminal.app. Workspace é opcional. A primeira chamada não é feita no workspace.

Mantenha auth login em primeiro plano até que ele saia com 0 se você o executou. O comando reimprime a URL a cada poucos segundos e consulta Convex / ~/.apiclaw.toml até que o login escreva session_token. Mostre ao humano a URL de login em cada reimpressão. Diga a eles para concluir o login nessa URL (que Autoriza). Se já estiver logado, diga a eles para clicar em Autorizar. Nao coloque o comando em segundo plano. Não continue até que whoami imprima um e-mail.

Se o navegador disser "conexão recusada" após Autorizar, tudo bem. Fique em apiclaw.cloud. Repita whoami — ele resgata o clique Autorizar mesmo se auth login foi encerrado ou localhost nunca respondeu.

Se ~/.apiclaw.toml ou ~/.apiclaw/session já tiver uma sessão, pule o login e vá para whoami.

Headless ou SSH: mostre ao humano a URL da primeira linha. Eles a abrem em outro dispositivo e confirmam com whoami. O arquivo ainda contém session_token. Copie ~/.apiclaw.toml para a máquina headless, ou execute a partir da máquina que concluiu o login. Não execute auth login em uma máquina que eles não podem ver.

Completamente headless (sem navegador em lugar nenhum, ex.: CI): pule o login CLI nesse host. Crie uma chave em Workspace > Connections e defina APICLAW_API_KEY lá. Essa é uma porta HTTP separada, não o caminho da primeira execução.

Regras:

  • Não peça ao usuário para criar uma chave de API em um painel.
  • Não peça ao usuário para colar session_token, sk-claw-… ou qualquer bearer neste chat.
  • Leia session_token de ~/.apiclaw.toml (ou sessionToken de ~/.apiclaw/session) quando você precisar de um cabeçalho. Nunca imprima o token bruto de volta para o usuário.
  • Não execute apiclaw call ou curl POST /v1/execute até que whoami imprima um e-mail. Um X-APIClaw-Session vazio é uma primeira execução falha.
  • Instalação, first_run ou uma URL de login impressa não é "pronto".

3. Confirme com whoami. Repita até que ele imprima um e-mail.

npx @nordsym/apiclaw auth whoami

whoami deve imprimir um e-mail e workspace antes de qualquer execução. whoami não é "Concluído". "Concluído" é HTTP 200 de POST /v1/execute. Mas whoami é o portão. Pule-o e a execução não será autenticada.

Repita whoami. Cada falha:

  • Mostre ao humano o login_url ativo (/auth/cli?authId=). whoami reimprime a URL pendente se o login já começou. Não imprima apenas npx @nordsym/apiclaw auth login.
  • Mantenha auth login em execução se ainda estiver esperando.
  • Se eles já clicaram em Autorizar, execute whoami novamente. Ele resgata a reivindicação e escreve session_token sem localhost.
  • Execute whoami novamente. Não pare após uma falha.
  • Não execute npx @nordsym/apiclaw call.
  • Não use curl POST /v1/execute.
  • Não envie um X-APIClaw-Session vazio.

Somente depois que whoami imprimir um e-mail, execute NASA APOD, depois Frankfurter latest se NASA não retornar 200.

4. Primeira execução — POST /v1/execute

Somente depois que whoami imprimir um e-mail. Chamada de pesquisa preferida: NASA APOD. Plano de fallback é Frankfurter latest (gratuito, sem chave, sem cartão) para que o primeiro 200 ainda chegue se NASA estiver fora do ar. Não comece com pesquisa paga (Brave, Serper, Firecrawl).

Rota preferida: NASA APOD

A forma de barra CLI lê session_token de ~/.apiclaw.toml e envia X-APIClaw-Session. Use esta primeiro. Não peça ao usuário para colar um token. O CLI recusa localmente se whoami falhar. Ele não fará POST de um cabeçalho de sessão vazio.

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

Equivalente HTTP — mesmo session_token, mesmo cabeçalho X-APIClaw-Session. Extraia o valor localmente. Não o imprima. Não use api_key. Recuse se a extração estiver vazia. Não faça POST de um cabeçalho vazio.

npx @nordsym/apiclaw auth whoami || { echo "Pare. Conclua Clerk. Mostre ao humano a URL de login. Não faça 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 "Pare. Nenhum session_token. Não faça POST /v1/execute com um X-APIClaw-Session vazio."; 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":{}}'

Um 200 com um título APOD é sucesso. nasa/apod é uma API gratuita: sem cartão necessário.

Rota de fallback: Frankfurter latest

Se NASA não retornar 200, busque as taxas de câmbio do ECB de hoje. Mesmo portão whoami. Mesmo $SESSION não vazio. Não use curl se $SESSION estiver vazio. Esta é a mesma rota de último recurso que a primeira execução automática usa após Autorizar. É gratuita para sempre, sem cartão, sem chave. Brave / Serper / Firecrawl são APIs de pesquisa pagas e retornarão payment_required em um novo workspace — não as use para a primeira execução.

npx @nordsym/apiclaw call frankfurter/latest --params '{"path":"/latest"}' --idempotency-key "apiclaw-first-frankfurter-$(date +%s)"
if [ -z "$SESSION" ]; then echo "Pare. Nenhum session_token. Não faça POST /v1/execute com um X-APIClaw-Session vazio."; 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 ainda é session_token de ~/.apiclaw.toml, mesma extração que o curl NASA. Mesmo cabeçalho que a forma de barra CLI envia.

Um 200 com uma taxa EUR/USD é sucesso.

Regras de execução

  • Sempre POST https://api.apiclaw.cloud/v1/execute com { "provider", "action", "params" }.
  • Nunca passe um nome de exibição do catálogo para apiclaw call. Nomes sem uma barra atingem o legado POST /v1/call.
  • Chamadas HTTP gerenciadas precisam de uma Idempotency-Key por operação lógica. Reutilize a mesma chave após uma falha de rede ambígua.
  • Após o login, execute whoami. Só então execute a forma de barra CLI NASA (ou o curl que extrai session_token). Se não for 200, execute Frankfurter latest. Não invente uma rota de pesquisa paga.

5. Após o primeiro 200

A primeira chamada permanece gratuita (NASA APOD, Frankfurter latest se NASA não for 200). Não faça da primeira chamada uma API paga.

Depois que esse 200 chegar, você pode sugerir um próximo passo pago barato (por exemplo, OpenRouter chat). Mostre ao humano https://apiclaw.cloud/upgrade para que ele possa adicionar um cartão uma vez. APIs gratuitas permanecem gratuitas. APIs pagas cobram o custo do provedor mais 15%.

Se uma chamada posterior retornar payment_required (HTTP 402), mostre o upgradeUrl (https://apiclaw.cloud/upgrade). Peça ao humano para adicionar um cartão e repita a mesma chamada. Não invente uma API diferente.

Descubra apenas o que é chamável agora:

npx @nordsym/apiclaw discover "taxas de câmbio" --callable

Ou:

POST https://apiclaw.cloud/v1/discover
{ "query": "taxas de câmbio", "callable_only": true }

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

Em seguida, execute com provider / action em POST /v1/execute. Não colete chaves de API de provedor do usuário.

6. Traga sua própria chave (válvula de escape)

Você não precisa de suas próprias chaves. O objetivo do APIClaw é um único login, sem coleta de chaves. Se seu workspace já tem sua própria chave OpenRouter, você pode adicioná-la em Workspace, Connections, Suas chaves e rotear conclusões de chat através dela gratuitamente, sem cartão. O provedor cobra o workspace diretamente. Isso é separado da chave APIClaw usada para autenticar no gateway. Hoje isso cobre uma chave OpenRouter para POST /v1/chat/completions, não todos os provedores.

Outras portas (mesmo workspace)

  • Skill (este arquivo): 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

Preços (não invente)

  • APIs gratuitas: gratuitas para sempre, sem cartão. Descoberta e todas as APIs de custo zero, mais de 1.000 das 1.025 chamáveis.
  • APIs pagas: adicione um cartão uma vez, depois custo do provedor mais 15%, medido por chamada.
  • Sua chave: traga sua própria chave OpenRouter e roteie conclusões de chat através dela gratuitamente, sem cartão.
  • Execução pública anônima sem chave está desabilitada.

O que não fazer

  • Não peça ao usuário para colar um token no chat.
  • Não use nomes de exibição do catálogo ou POST /v1/call.
  • Não afirme contagem de instalações, contagem de ferramentas ou cobertura que você não leu de /api/catalog ou deste arquivo.
  • Não exponha provedores apenas internos. Os cards do catálogo público são a fonte da verdade para o que um cliente pode chamar.
  • Não faça POST /v1/execute antes de whoami ter sucesso.
  • Não envie um X-APIClaw-Session vazio.
  • Não diga ao humano para abrir Terminal.app ou voltar a um shell.
  • Após Autorizar, continue neste chat e execute NASA APOD você mesmo.

Habilidades Relacionadas