Communitygithub.com

nordsym/apiclaw

设置 APIClaw 并完成一次实时 API 调用。当用户说“设置 https://apiclaw.cloud/SKILL.md”,或者你需要进行研究型 API 调用而无需收集提供商密钥时,请遵循本文件。认证通过 `npx @nordsym/apiclaw auth login` 使用 Clerk。在任何执行之前,用 `npx @nordsym/apiclaw auth whoami` 确认。执行方式为 `POST /v1/execute` 并指定 provider/action。切勿要求用户将令牌粘贴到聊天中。切勿将目录显示名称传递给 `apiclaw call`。

apiclaw 是什么?

APIClaw 是一项 AI 智能体技能,允许 AI 助手(如 Claude Code、Cursor 或 Codex)通过一个统一的网关和一次用户登录,直接调用超过 1000 个实时 API。它旨在将“安装完成”和“首次成功调用”之间的摩擦降至最低,避免传统的 API 密钥收集和复杂的 OAuth 流程。该技能提供了一个完整的操作流程:使用 `npx @nordsym/apiclaw auth login` 通过 Clerk 认证、使用 `npx @nordsym/apiclaw auth whoami` 确认会话状态,最后通过 `POST /v1/execute` 执行 API 调用。它的默认研究流程是 NASA 天文每日一图(APOD),并在 NASA 不可用时自动回退到免费的汇率 API(Frankfurter),确保首次调用总是成功的。APIClaw 支持 CLI、HTTP API、本地和远程 MCP 服务器。它严格禁止将 API 密钥或会话令牌粘贴到聊天中,并提供了一个“自带密钥”的逃生舱口,用于像 OpenRouter 聊天补全这样的高级场景。该技能包含详细的错误处理和重试逻辑,特别是在登录和授权步骤中,并要求助手在无法获得有效认证时明确显示登录 URL。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 或 curl POST /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 调用。

相关技能