nordsym/apiclaw

apiclaw 是做什么的？

Your agent calls real APIs. You sign in once. One workspace. Clerk auth. The metric that matters is a successful POST /v1/execute, not an install.

Give an agent this file and it can install, sign in, and land one 200 without guessing.

Live catalog (2026-08-25). Use https://apiclaw.cloud/api/catalog if counts must be current. Do not invent metrics.

• 1,025 callable
• 26,619 discoverable
• 22 built-in providers

Identity and product truth live at https://apiclaw.cloud/llms.txt. This file is the operational door: auth, then whoami, then execute.

1. Install

Node.js 18+ and npx are enough. A global install is optional.

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

Human shell door (same package, local MCP):

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

2. Auth (Clerk). Never paste a token into chat.

Unsigned MCP / CLI first_run mints a pending login even with no TTY and prints the exact https URL as the first line of the tool/CLI response (then repeats it as login_url in JSON). The first lines look like:

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

STOP. Show the human the login URL on the first line. Do not summarize it away. Do not execute.

Show the human that first-line URL on its own line so they can click it. Do not bury it. Do not summarize the tool result. Do not only print npx @nordsym/apiclaw auth login. A command without /auth/cli?authId= is not enough.

If you are running on a machine the human cannot see (Grok Bot, cloud VM, headless agent), do not run auth login there — that opens a browser they will never get. The first-line URL in the tool response is the only door. Show it. Stop. Wait.

npx @nordsym/apiclaw auth login

That command is the human-shell door on a machine they can see. It opens the same browser URL (or reuses the pending one). Finish Google or email on that URL. Completing sign-in there Authorizes this agent (one action). If you are already signed in, click Authorize. Do not tell a new user they still need a second click after sign-in. Only then does the CLI write session_token to ~/.apiclaw.toml. Printing the URL is not success. Do not declare ready. Do not execute.

After the human finishes Authorize, stay in this chat. Retry here. You confirm with whoami and you execute NASA APOD (Frankfurter latest if NASA is not 200) in this same session. Do not send the human to a terminal. Do not tell them to open Terminal.app. Workspace is optional. The first call is not made in the workspace.

Keep auth login in the foreground until it exits 0 if you ran it. The command reprints that URL every few seconds and polls Convex / ~/.apiclaw.toml until sign-in writes session_token. Show the human the login URL on every reprint. Tell them to finish sign-in on that URL (that Authorizes). If already signed in, tell them to click Authorize. Do not background the command. Do not continue until whoami prints an email.

If the browser says connection refused after Authorize, that is OK. Stay on apiclaw.cloud. Loop whoami — it redeems the Authorize click even if auth login was killed or localhost never answered.

If ~/.apiclaw.toml or ~/.apiclaw/session already has a session, skip login and go to whoami.

Headless or SSH: show the human the first-line URL. They open it on another device, then confirm with whoami. The file still holds session_token. Copy ~/.apiclaw.toml to the headless machine, or run execute from the machine that finished login. Do not run auth login on a machine they cannot see.

Fully headless (no browser anywhere, e.g. CI): skip CLI login on that host. Create a key in Workspace > Connections and set APICLAW_API_KEY there. That is a separate HTTP door, not the first-execute path.

Rules:

• Do not ask the user to create an API key in a dashboard.
• Do not ask the user to paste session_token, sk-claw-…, or any bearer into this chat.
• Read session_token from ~/.apiclaw.toml (or sessionToken from ~/.apiclaw/session) when you need a header. Never print the raw token back to the user.
• Do not run apiclaw call or curl POST /v1/execute until whoami prints an email. An empty X-APIClaw-Session is a failed first-run.
• Install, first_run, or a printed login URL is not ready.

3. Confirm with whoami. Loop until it prints an email.

npx @nordsym/apiclaw auth whoami

whoami must print an email and workspace before any execute. whoami is not Done. Done is HTTP 200 from POST /v1/execute. But whoami is the gate. Skip it and the execute will be unauthenticated.

Loop whoami. Each miss:

• Show the human the live login_url (/auth/cli?authId=). whoami reprints the pending URL if login already started. Do not only print npx @nordsym/apiclaw auth login.
• Keep auth login running if it is still waiting.
• If they already clicked Authorize, run whoami again. It redeems the claim and writes session_token without localhost.
• Run whoami again. Do not stop after one miss.
• Do not run npx @nordsym/apiclaw call.
• Do not curl POST /v1/execute.
• Do not send an empty X-APIClaw-Session.

Only after whoami prints an email, execute NASA APOD, then Frankfurter latest if NASA is not 200.

4. First execute — POST /v1/execute

Only after whoami prints an email. Preferred research call: NASA APOD. Fallback is Frankfurter latest (free, no key, no card) so the first 200 still lands if NASA is down. Do not lead with billed research (Brave, Serper, Firecrawl).

Preferred rail: NASA APOD

CLI slash form reads session_token from ~/.apiclaw.toml and sends X-APIClaw-Session. Use this first. Do not ask the user to paste a token. The CLI refuses locally if whoami would fail. It will not POST an empty session header.

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

HTTP equivalent — same session_token, same X-APIClaw-Session header. Extract the value locally. Do not print it. Do not use api_key. Refuse if the extract is empty. Do not POST an empty header.

npx @nordsym/apiclaw auth whoami || { echo "Stop. Finish Clerk. Show the human the login URL. Do not 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 "Stop. No session_token. Do not POST /v1/execute with an empty X-APIClaw-Session."; 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":{}}'

A 200 with an APOD title is success. nasa/apod is a Free API: no card needed.

Fallback rail: Frankfurter latest

If NASA is not 200, fetch today's ECB FX rates. Same whoami gate. Same nonempty $SESSION. Do not curl if $SESSION is empty. This is the same last-resort rail the automatic first execute uses after Authorize. It is free forever, no card, no key. Brave / Serper / Firecrawl are paid research APIs and will return payment_required on a new workspace — do not use them for first execute.

npx @nordsym/apiclaw call frankfurter/latest --params '{"path":"/latest"}' --idempotency-key "apiclaw-first-frankfurter-$(date +%s)"

if [ -z "$SESSION" ]; then echo "Stop. No session_token. Do not POST /v1/execute with an empty X-APIClaw-Session."; 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 is still session_token from ~/.apiclaw.toml, same extract as the NASA curl. Same header the CLI slash form sends.

A 200 with a EUR/USD rate is success.

Execute rules

• Always POST https://api.apiclaw.cloud/v1/execute with { "provider", "action", "params" }.
• Never pass a catalog display name to apiclaw call. Names without a slash hit legacy POST /v1/call.
• Managed HTTP calls need one Idempotency-Key per logical operation. Reuse the same key after an ambiguous network failure.
• After login, run whoami. Only then run the NASA CLI slash form (or the curl that extracts session_token). If it is not 200, run Frankfurter latest. Do not invent a billed-research rail.

5. After the first 200

The first call stays free (NASA APOD, Frankfurter latest if NASA is not 200). Do not make the first call a paid API.

After that 200 lands, you may suggest one cheap paid next step (for example OpenRouter chat). Show the human https://apiclaw.cloud/upgrade so they can add a card once. Free APIs stay free. Paid APIs bill provider cost plus 15%.

If a later call returns payment_required (HTTP 402), show the upgradeUrl (https://apiclaw.cloud/upgrade). Ask the human to add a card, then retry the same call. Do not invent a different API.

Discover only what is callable now:

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

Or:

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

Live catalog: https://apiclaw.cloud/api/catalog?callable=true.

Then execute with provider / action on POST /v1/execute. Do not collect provider API keys from the user.

6. Bring your own key (escape hatch)

You do not need your own keys. APIClaw's point is one sign-in, no key collecting. If your workspace already has its own OpenRouter key, you can add it in Workspace, Connections, Your keys, and route chat completions through it for free, no card. The provider bills the workspace directly. This is separate from the APIClaw key used to authenticate into the gateway. Today this covers an OpenRouter key for POST /v1/chat/completions, not every provider.

Other doors (same workspace)

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

Pricing (do not invent)

• Free APIs: free forever, no card. Discovery and every zero-cost API, over 1,000 of the 1,025 callable.
• Paid APIs: add a card once, then provider cost plus 15%, metered per call.
• Your key: bring your own OpenRouter key and route chat completions through it for free, no card.
• Anonymous keyless public execution is disabled.

What not to do

• Do not ask the user to paste a token into chat.
• Do not use catalog display names or POST /v1/call.
• Do not claim install count, tool count, or coverage you did not read from /api/catalog or this file.
• Do not expose internal-only providers. Public catalog cards are the source of truth for what a customer can call.
• Do not POST /v1/execute before whoami succeeds.
• Do not send an empty X-APIClaw-Session.
• Do not tell the human to open Terminal.app or go back to a shell.
• After Authorize, continue in this chat and land NASA APOD yourself.