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_tokende~/.apiclaw.toml(ousessionTokende~/.apiclaw/session) quando você precisar de um cabeçalho. Nunca imprima o token bruto de volta para o usuário. - Não execute
apiclaw callou curlPOST /v1/executeaté que whoami imprima um e-mail. UmX-APIClaw-Sessionvazio é 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_urlativo (/auth/cli?authId=). whoami reimprime a URL pendente se o login já começou. Não imprima apenasnpx @nordsym/apiclaw auth login. - Mantenha
auth loginem execução se ainda estiver esperando. - Se eles já clicaram em Autorizar, execute whoami novamente. Ele resgata
a reivindicação e escreve
session_tokensem 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-Sessionvazio.
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/executecom{ "provider", "action", "params" }. - Nunca passe um nome de exibição do catálogo para
apiclaw call. Nomes sem uma barra atingem o legadoPOST /v1/call. - Chamadas HTTP gerenciadas precisam de uma
Idempotency-Keypor 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/catalogou 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/executeantes de whoami ter sucesso. - Não envie um
X-APIClaw-Sessionvazio. - 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.