apiclaw 是做什麼的?
你的代理人可以直接呼叫真實 API。你只需登入一次。一個工作區。Clerk 驗證。
真正重要的指標是成功的 POST /v1/execute,而不是安裝次數。
將此檔案交給代理人,它就能完成安裝、登入,並在無需猜測的情況下取得 200 狀態碼。
即時目錄(2026-08-25)。如需最新計數,請使用 https://apiclaw.cloud/api/catalog。請勿自行編造數據。
- 1,025 個可呼叫
- 26,619 個可探索
- 22 個內建提供者
身分與產品資訊位於 https://apiclaw.cloud/llms.txt。
此檔案是操作入口:先驗證,再 whoami,最後執行。
1. 安裝
Node.js 18+ 與 npx 即可。全域安裝為選項。
npx -y @nordsym/apiclaw@latest --version
人類終端機入口(相同套件,本機 MCP):
curl -fsSL https://apiclaw.cloud/install.sh | bash
2. 驗證(Clerk)。切勿將 Token 貼到對話中。
未簽署的 MCP / CLI 首次執行時,即使在沒有 TTY 的環境下也會產生一個待處理的登入請求,並將確切的 HTTPS URL 列印為工具/CLI 回應的第一行(然後在 JSON 中以 login_url 重複顯示)。第一行看起來像:
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.
將第一行的 URL 單獨一行顯示給使用者,讓他們可以點擊。不要隱藏它。不要總結工具結果。不要只顯示 npx @nordsym/apiclaw auth login。不包含 /auth/cli?authId= 的指令是不夠的。
如果你在一個使用者無法看到的機器上執行(Grok Bot、雲端 VM、無頭代理人),請不要在那裡執行 auth login——那會打開一個他們永遠看不到的瀏覽器。工具回應中的第一行 URL 是唯一的入口。顯示它。停下。等待。
npx @nordsym/apiclaw auth login
這個指令是在使用者可看到的機器上的人類終端機入口。它會打開相同的瀏覽器 URL(或重複使用待處理的 URL)。在那個 URL 上完成 Google 或電子郵件登入。完成登入後會授權這個代理人(一個動作)。如果你已登入,請點擊「Authorize」。不要告訴新使用者在登入後還需要第二次點擊。只有在那之後,CLI 才會將 session_token 寫入 ~/.apiclaw.toml。印出 URL 不代表成功。不要宣告準備就緒。不要執行。
在使用者完成「Authorize」後,留在這個對話中。在此重試。你透過 whoami 確認身分,並在同一工作階段中執行 NASA APOD(若 NASA 不是 200,則執行 Frankfurter latest)。不要將使用者送到終端機。不要叫他們打開 Terminal.app。工作區為選項。第一次呼叫不在工作區中進行。
如果你有執行 auth login,請讓它保持在前景直到它退出代碼 0。該指令每隔幾秒會重新印出該 URL,並輪詢 Convex / ~/.apiclaw.toml,直到登入成功寫入 session_token。每次重新印出時,都將登入 URL 顯示給使用者。告訴他們在該 URL 上完成登入(這會進行授權)。如果已經登入,告訴他們點擊「Authorize」。不要將指令放在背景執行。不要繼續,直到 whoami 印出一個電子郵件。
如果在「Authorize」後瀏覽器顯示連線被拒絕,沒關係。停留在 apiclaw.cloud 上。重複執行 whoami——它會兌現「Authorize」的點擊,即使 auth login 已被終止或 localhost 從未回應。
如果 ~/.apiclaw.toml 或 ~/.apiclaw/session 已有工作階段,請跳過登入,直接執行 whoami。
無頭或 SSH 環境:將第一行 URL 顯示給使用者。他們在其他裝置上打開它,然後用 whoami 確認。該檔案仍然會持有 session_token。將 ~/.apiclaw.toml 複製到無頭機器,或從完成登入的機器上執行。不要在他們看不到的機器上執行 auth login。
完全無頭(沒有任何瀏覽器,例如 CI):在該主機上跳過 CLI 登入。在工作區 > 連線 (Workspace > Connections) 中建立一個金鑰,並在那裡設定 APICLAW_API_KEY。這是一個獨立的 HTTP 入口,不是首次執行路徑。
規則:
- 不要要求使用者在儀表板中建立 API 金鑰。
- 不要要求使用者將
session_token、sk-claw-…或任何 bearer token 貼到這個對話中。 - 當你需要標頭時,從
~/.apiclaw.toml讀取session_token(或從~/.apiclaw/session讀取sessionToken)。切勿將原始 token 印回給使用者。 - 在 whoami 印出電子郵件之前,不要執行
apiclaw call或 curlPOST /v1/execute。空的X-APIClaw-Session表示首次執行失敗。 - 安裝、首次執行或印出的登入 URL 不代表準備就緒。
3. 使用 whoami 確認。重複執行直到它印出電子郵件。
npx @nordsym/apiclaw auth whoami
在執行任何操作之前,whoami 必須印出電子郵件和工作區。Whoami 不是完成。完成是 POST /v1/execute 回傳 HTTP 200。但 whoami 是閘門。跳過它,執行將會未經驗證。
重複執行 whoami。每次失敗:
- 將即時的
login_url(/auth/cli?authId=)顯示給使用者。如果登入已開始,whoami 會重新印出待處理的 URL。不要只印出npx @nordsym/apiclaw auth login。 - 如果
auth login仍在等待,請保持它在執行。 - 如果他們已經點擊了「Authorize」,再次執行 whoami。它會兌現請求並在不經過 localhost 的情況下寫入
session_token。 - 再次執行 whoami。不要在一次失敗後就停止。
- 不要執行
npx @nordsym/apiclaw call。 - 不要 curl
POST /v1/execute。 - 不要發送空的
X-APIClaw-Session。
只有在 whoami 印出電子郵件後,才執行 NASA APOD,如果 NASA 不是 200,則執行 Frankfurter latest。
4. 首次執行 — POST /v1/execute
只有在 whoami 印出電子郵件之後。首選的研究型呼叫: NASA APOD。備用方案是 Frankfurter latest(免費,無需金鑰,無需信用卡) 這樣即使 NASA 故障,首次 200 仍然能成功。不要以付費研究型 API(Brave、Serper、Firecrawl)作為首次呼叫。
首選路線:NASA APOD
CLI 斜線形式會從 ~/.apiclaw.toml 讀取 session_token 並發送
X-APIClaw-Session。請優先使用此方式。不要要求使用者貼上 token。
如果 whoami 會失敗,CLI 會在本機拒絕執行。它不會發送空的 session 標頭。
npx @nordsym/apiclaw call nasa/apod --params '{}' --idempotency-key "apiclaw-first-nasa-$(date +%s)"
HTTP 等效方式 —— 相同的 session_token,相同的 X-APIClaw-Session 標頭。
在本機提取該值。不要印出它。不要使用 api_key。
如果提取結果為空則拒絕。不要發送空的標頭。
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":{}}'
回傳 200 並包含 APOD 標題即為成功。nasa/apod 是免費 API:無需信用卡。
備用路線:Frankfurter latest
如果 NASA 不是 200,則取得今日的 ECB 匯率。相同的 whoami 閘門。
相同的非空 $SESSION。如果 $SESSION 為空則不要執行 curl。
這是自動首次執行在「Authorize」後使用的相同最後手段路線。永遠免費,無需信用卡,無需金鑰。
Brave / Serper / Firecrawl 是付費研究型 API,在新的工作區上會回傳 payment_required —— 不要將它們用於首次執行。
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 仍然來自 ~/.apiclaw.toml 的 session_token,與 NASA curl 的提取方式相同。這是 CLI 斜線形式發送的相同標頭。
回傳 200 並包含 EUR/USD 匯率即為成功。
執行規則
- 始終使用
POST https://api.apiclaw.cloud/v1/execute,並帶有{ "provider", "action", "params" }。 - 切勿將目錄顯示名稱傳遞給
apiclaw call。不含斜線的名稱會打到舊版POST /v1/call。 - 受管理的 HTTP 呼叫每次邏輯操作需要一個
Idempotency-Key。 在網路失敗不明確的情況下,重複使用相同的金鑰。 - 登入後,執行 whoami。然後才執行 NASA CLI 斜線形式(或
提取
session_token的 curl)。如果它不是 200,則執行 Frankfurter latest。不要自行發明一個付費研究型路線。
5. 首次 200 之後
首次呼叫保持免費(NASA APOD,如果 NASA 不是 200 則為 Frankfurter latest)。不要讓首次呼叫成為付費 API。
在該 200 成功後,你可以建議一個便宜的付費下一步 (例如 OpenRouter 聊天)。向使用者顯示 https://apiclaw.cloud/upgrade 以便他們可以新增一次信用卡。免費 API 保持免費。 付費 API 的費用為提供者成本加 15%。
如果後續呼叫回傳 payment_required(HTTP 402),請顯示
upgradeUrl(https://apiclaw.cloud/upgrade)。要求使用者新增
信用卡,然後重試相同的呼叫。不要自行發明不同的 API。
僅探索當前可呼叫的內容:
npx @nordsym/apiclaw discover "exchange rates" --callable
或:
POST https://apiclaw.cloud/v1/discover
{ "query": "exchange rates", "callable_only": true }
即時目錄:https://apiclaw.cloud/api/catalog?callable=true。
然後使用 POST /v1/execute 並提供 provider / action 來執行。
不要向使用者收集提供者 API 金鑰。
6. 自備金鑰(逃脫機制)
你不需要自己的金鑰。APIClaw 的重點就是一次登入,無需收集金鑰。
如果你的工作區已經有自己的 OpenRouter 金鑰,你可以在
工作區 > 連線 > 你的金鑰 (Workspace, Connections, Your keys) 中新增它,
並透過它免費路由聊天完成請求,無需信用卡。提供者會直接向工作區收費。
這與用來驗證閘道器的 APIClaw 金鑰是分開的。目前這涵蓋了用於
POST /v1/chat/completions 的 OpenRouter 金鑰,並非所有提供者。
其他入口(相同工作區)
- 技能(此檔案):
https://apiclaw.cloud/SKILL.md - curl|bash / 本機 MCP:
curl -fsSL https://apiclaw.cloud/install.sh | bash - CLI:
npx @nordsym/apiclaw --help - HTTP:
POST https://api.apiclaw.cloud/v1/execute - 遠端 MCP:
https://apiclaw.cloud/mcp
定價(請勿自行編造)
- 免費 API:永遠免費,無需信用卡。探索以及所有零成本 API, 超過 1,025 個可呼叫中的 1,000 個。
- 付費 API:新增一次信用卡,然後為提供者成本加 15%,按次計費。
- 你的金鑰:自備 OpenRouter 金鑰,並透過它免費路由聊天完成請求,無需信用卡。
- 匿名免金鑰公開執行已停用。
禁止事項
- 不要要求使用者將 Token 貼到對話中。
- 不要使用目錄顯示名稱或
POST /v1/call。 - 不要聲稱你未從
/api/catalog或此檔案讀取到的安裝次數、工具數量或覆蓋範圍。 - 不要暴露僅限內部的提供者。公共目錄卡片是客戶可以呼叫什麼的真實來源。
- 在 whoami 成功之前,不要執行
POST /v1/execute。 - 不要發送空的
X-APIClaw-Session。 - 不要告訴使用者打開 Terminal.app 或返回 Shell 視窗。
- 在「Authorize」之後,繼續在此對話中進行,並自行完成 NASA APOD 的執行。