How to Use ToolRelay

从拿到 API Key 到跑通一次 Agent 调用，只走三步。

ToolRelay 是给 Agent 用的统一能力 API：模型、搜索、网页读取、图片/视频生成、TTS 都走一把 key。这个页面不让用户先啃 API 文档，而是直接给可复制的上手路径。

打开 Dashboard

最短路径

1拿到 key登录后进入 Dashboard，复制默认 setup block，或者在 API Keys 里创建一把具名 key。
2教会 agent把 skill line 和 API key 粘贴到 Codex、Claude Code、Cursor，或任何能读取远程 skill 文档的 agent。
3跑通 curl先调用 web.read。curl 成功后，agent 就能复用同一把 key 和 base URL。

ToolRelay 是什么

ToolRelay 是给 Agent 用的统一 API。Agent 只说要做什么能力，ToolRelay 负责路由到合适的上游 provider，记录 usage，并且只对成功调用扣 credits。

One key

TOOLRELAY_API_KEY

One API

https://toolrelay.dev

One skill

toolrelay.dev/skill.md

1. 使用 ToolRelay Skill

skill.md 会告诉 agent 什么时候该用 ToolRelay、有哪些 endpoint、如何处理成本、会遇到哪些错误。下面这行是给 agent 看的指令，不是 shell 命令。

Terminal

set up toolrelay.dev/skill.md
TOOLRELAY_API_KEY=tr_live_...

skill.md

请保护 live key。不要把它贴到公开仓库、issue 或截图里。

打开 skill.md 打开 API 文档

2. 配置 API Key

Agent 和终端都需要同一把 key。bash/zsh 用 export。fish 要用 set，因为 KEY=value 在 fish 里不是合法语法。

bash / zsh

Terminal

export TOOLRELAY_BASE_URL="https://toolrelay.dev"
export TOOLRELAY_API_KEY="tr_live_..."

fish

Terminal

set -x TOOLRELAY_BASE_URL "https://toolrelay.dev"
set -x TOOLRELAY_API_KEY "tr_live_..."

3. 跑一个真实 curl

建议从 web.read 开始，因为结果最容易验证：成功响应里应该有干净的页面内容、usage 元数据，并在 provider 成功时记录一次扣费 execution。

Terminal

curl -X POST https://toolrelay.dev/v1/relay \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "capability": "web.read",
    "input": { "url": "https://example.com" },
    "maxCostUsd": 0.05
  }'

Terminal

curl -X POST https://toolrelay.dev/v1/chat/completions \
  -H "authorization: Bearer $TOOLRELAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "openrouter/openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Say hello in one sentence." }]
  }'

4. 接入自己的 Agent 工作流

第一次 curl 跑通后，把下面的模式复制到你实际使用的 agent 或 IDE 里。

Codex

当你需要实时搜索、读取网页、生成图片/视频或 TTS 时使用 ToolRelay。先读取 toolrelay.dev/skill.md。

npx toolrelay install codex

Claude Code

安装 ToolRelay skill，然后用 TOOLRELAY_API_KEY 调用 web.read、web.search、chat/model、image/video、tts。

npx toolrelay install claude

Cursor 或 MCP client

把 ToolRelay 加成 MCP 或 shell-backed capability provider。key 放在本地环境变量里，不要写进项目文件。

npx toolrelay install cursor

Claude Code
Codex
Cursor
Windsurf
Cline
Gemini CLI
任意 MCP 客户端

当前可用能力

先按 capability 理解，不要先想 vendor。Agent 要描述任务，ToolRelay 再决定底层走哪个 provider。

CapabilityEndpointProvider

chat/model/v1/chat/completionsOpenRouter

web.search/v1/relayTavily

web.read / scrape/v1/relayFirecrawl

image.generate/v1/relayReplicate

video.generate/v1/relayReplicate

tts.generate/v1/relayElevenLabs

Done

什么叫已经会用了

你能复制 setup block、配置 TOOLRELAY_API_KEY、跑通 curl，并且知道 skill.md 是给 Agent 看的 instruction layer，就已经完成上手。

打开 Dashboard