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,然后 execute。
1. 安装
需要 Node.js 18+ 和 npx。全局安装是可选的。
npx -y @nordsym/apiclaw@latest --version
人类终端入口(相同包,本地 MCP):
curl -fsSL https://apiclaw.cloud/install.sh | bash
2. 认证 (Clerk)。切勿将令牌粘贴到聊天中。
未签名的 MCP / CLI 首次运行会在没有 TTY 的情况下生成一个待处理的登录,并打印确切的 https URL 作为工具/CLI 响应的第一行(然后在 JSON 中重复作为 login_url)。第一行看起来像:
https://apiclaw.cloud/auth/cli?authId=…
STOP。向人类显示第一行的登录 URL。不要将其概括掉。不要执行。
将第一行的 URL 单独一行显示给人类,以便他们可以点击。不要隐藏它。不要总结工具结果。不要只打印 npx @nordsym/apiclaw auth login。没有 /auth/cli?authId= 的命令是不够的。
如果您在人类无法看到的机器上运行(Grok Bot、云虚拟机、无头智能体),请不要在那里运行 auth login —— 那会打开一个他们永远看不到的浏览器。工具响应中的第一行 URL 是唯一的入口。显示它。停下来。等待。
npx @nordsym/apiclaw auth login
该命令是人类在可见机器上的终端入口。它会打开相同的浏览器 URL(或重用待处理的 URL)。在该 URL 上完成 Google 或电子邮件登录。在此完成登录后授权此智能体(一次操作)。如果您已经登录,请点击“Authorize”。不要告诉新用户登录后还需要第二次点击。只有这样,CLI 才会将 session_token 写入 ~/.apiclaw.toml。打印 URL 并不算成功。不要声明就绪。不要执行。
在人类完成授权后,请留在本次对话中。在此重试。您用 whoami 确认,并在同一会话中执行 NASA APOD(如果 NASA 未返回 200,则回退到 Frankfurter 最新汇率)。不要将人类发送到终端。不要告诉他们打开 Terminal.app。工作区是可选的。第一次调用不在工作区中进行。
如果您运行了 auth login,请将其保持在前台直到退出码为 0。该命令每隔几秒重新打印该 URL,并轮询 Convex / ~/.apiclaw.toml,直到登录写入 session_token。每次重新打印时向人类显示登录 URL。告诉他们在该 URL 上完成登录(这将完成授权)。如果已经登录,告诉他们点击“Authorize”。不要将该命令置于后台。不要继续,直到 whoami 打印出电子邮件。
如果授权后浏览器显示“连接被拒绝”,这没问题。停留在 apiclaw.cloud 上。循环执行 whoami —— 即使 auth login 被终止或 localhost 从未响应,它也会兑现授权点击。
如果 ~/.apiclaw.toml 或 ~/.apiclaw/session 已经包含会话,则跳过登录,直接进入 whoami。
无头或 SSH:向人类显示第一行 URL。他们在另一台设备上打开,然后用 whoami 确认。文件仍然包含 session_token。将 ~/.apiclaw.toml 复制到无头机器,或者在完成登录的机器上运行 execute。不要在人类无法看到的机器上运行 auth login。
完全无头(任何地方都没有浏览器,例如 CI):在该主机上跳过 CLI 登录。在工作区 > 连接中创建一个密钥,并在此处设置 APICLAW_API_KEY。这是一个单独的 HTTP 入口,不是首次执行路径。
规则:
- 不要要求用户在仪表板中创建 API 密钥。
- 不要要求用户将
session_token、sk-claw-…或任何 bearer 令牌粘贴到本聊天中。 - 当需要请求头时,从
~/.apiclaw.toml读取session_token(或从~/.apiclaw/session读取sessionToken)。切勿将原始令牌打印回给用户。 - 在 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。它会兑现声明并写入
session_token,无需 localhost。 - 再次运行 whoami。不要在一次失败后停止。
- 不要运行
npx @nordsym/apiclaw call。 - 不要 curl
POST /v1/execute。 - 不要发送空的
X-APIClaw-Session。
只有在 whoami 打印出电子邮件后,才执行 NASA APOD,如果 NASA 未返回 200 则执行 Frankfurter 最新汇率。
4. 首次执行 —— POST /v1/execute
只有在 whoami 打印出电子邮件之后。首选的研究调用: NASA APOD。后备方案是 Frankfurter 最新汇率(免费,无需密钥,无需信用卡),这样即使 NASA 宕机,首次 200 仍能成功。不要首先使用付费研究调用(Brave、Serper、Firecrawl)。
首选路径:NASA APOD
CLI 斜杠形式从 ~/.apiclaw.toml 读取 session_token 并发送 X-APIClaw-Session。首先使用此方法。不要要求用户粘贴令牌。如果 whoami 会失败,CLI 会在本地拒绝。它不会发送空的会话头。
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 "停止。完成 Clerk。向人类显示登录 URL。不要 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 "停止。没有 session_token。不要使用空的 X-APIClaw-Session 来 POST /v1/execute。"; 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 最新汇率
如果 NASA 未返回 200,获取今日 ECB 汇率。相同的 whoami 门禁。
相同的非空 $SESSION。如果 $SESSION 为空,不要执行 curl。
这与授权后自动首次执行使用的最后手段路径相同。它永远免费,无需信用卡,无需密钥。
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 "停止。没有 session_token。不要使用空的 X-APIClaw-Session 来 POST /v1/execute。"; 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 最新汇率。不要发明一个付费的研究路径。
5. 首次 200 之后
首次调用保持免费(NASA APOD,如果 NASA 未返回 200 则使用 Frankfurter 最新汇率)。不要将首次调用设为付费 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。
然后使用 provider / action 在 POST /v1/execute 上执行。
不要从用户那里收集提供商 API 密钥。
6. 自带密钥(逃生舱口)
您不需要自己的密钥。APIClaw 的意义在于一次登录,无需收集密钥。如果您的工作区已经有自己的 OpenRouter 密钥,您可以在工作区、连接、您的密钥中添加它,并通过它免费路由聊天补全,无需信用卡。提供商会直接向工作区收费。这与用于认证进入网关的 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 密钥,并通过它免费路由聊天补全,无需信用卡。
- 匿名无密钥的公开执行已被禁用。
禁止事项
- 不要要求用户将令牌粘贴到聊天中。
- 不要使用目录显示名称或
POST /v1/call。 - 不要声称您未从
/api/catalog或本文件读取的安装数、工具数或覆盖范围。 - 不要暴露仅限内部的提供商。公共目录卡片是客户可以调用什么的真实来源。
- 在 whoami 成功之前不要 POST
/v1/execute。 - 不要发送空的
X-APIClaw-Session。 - 不要告诉人类打开 Terminal.app 或返回终端。
- 授权后,留在本次对话中,并自行完成 NASA APOD 调用。