AI agent 须知

何时阅读本页复制链接

如果你是一个 AI agent（Claude Code、Cursor、Codex、ChatGPT 或其他），正在为用户配置通过 EZAT Router 调用 AI 模型的工具、SDK 或代码，或者在排查这类配置的问题，请阅读本页。

必需的值复制链接

可选的请求头，供你编写的代码使用：

见提示缓存。

安全的配置流程复制链接

1. 在看不到 key 的前提下找到它。询问用户哪个环境变量保存了他们的 EZAT Router key；建议使用 EZAT_API_KEY。不要让用户把 key 粘贴到对话里。如果用户还没有 key，告诉他们在 https://router.ezat.io/zh/keys 创建一个，并在他们自己的终端中 export。

2. 确认已经设置，但不打印它。只打印长度和前缀：

   复制

   printf 'length %s, prefix %s\n' "${#EZAT_API_KEY}" "${EZAT_API_KEY:0:8}"

   预期输出 length 48, prefix ezat_sk_。长度不对，通常是因为有引号、空格，或者复制不完整。

3. 验证 key，用一个不花钱的请求：

   curl

   复制

   curl --fail-with-body -sS -o /dev/null -w '%{http_code}\n' https://api.router.ezat.io/v1/models \
     -H "x-api-key: $EZAT_API_KEY"

   200 表示 key 可用。401 表示 key 缺失、输错、已过期或已被吊销：停下来告诉用户。

4. 选择模型。使用用户要求的模型，或者从 GET https://api.router.ezat.io/v1/models 中选一个。不要依赖你记忆中或本页上的列表。

5. 发送一个极小的请求，max_tokens 设得小一些：

   curl

   复制

   curl --fail-with-body -sS https://api.router.ezat.io/v1/messages \
     -H "x-api-key: $EZAT_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "content-type: application/json" \
     -d '{"model": "anthropic/claude-sonnet-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK."}]}'

   如果返回 402，说明组织没有余额，或者 key 达到了消费上限：告诉用户到 https://router.ezat.io/zh/billing 充值（或者换一个 key），然后停止。

6. 配置工具。使用工具所用的格式：

   • Claude Code 和 Anthropic SDK：base URL 为 https://api.router.ezat.io。Claude Code 使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN（Claude Code）。
   • OpenAI SDK 和 OpenAI 格式的工具：base URL 为 https://api.router.ezat.io/openai/v1（OpenAI 格式的工具）。
   • 你自己的代码：在服务器端，于运行时从环境变量读取 key。

   只把 key 放在用户级或不受版本控制的配置中。修改用户没有提到的全局配置文件之前，先征得同意。

7. 在工具内验证。通过工具本身发送一个请求。在 Claude Code 中，/status 会显示 base URL 和正在使用的凭据。

8. 出错时按错误类型处理。对 429、500 和 529（OpenAI 格式中为 503）按退避策略重试；如果有 retry-after 响应头，至少等待其中的秒数。非流式请求返回 504，表示模型耗时太长：改用流式输出重新发送。不要重试 400、401、402、403、404 或 413：先解决原因。见错误和故障排查。

禁止事项复制链接

• 不要让用户把 key 粘贴到对话里，也不要打印、echo 或记录 key，哪怕只是 ezat_sk_ 前缀之外的一部分。
• 不要把 key 写进会提交的文件：源代码、受版本控制的 .env、项目的 .claude/settings.json、仓库里的 CI 配置。
• 不要把 key 放进前端、浏览器或移动应用的代码，也不要放进 URL 或查询字符串。
• 不要在 https://api.router.ezat.io 后面加 /v1，也不要把 https://api.router.ezat.io 交给 OpenAI 客户端：它需要的是 https://api.router.ezat.io/openai/v1。
• 不要写死价格或模型列表。需要时读取 GET https://api.router.ezat.io/v1/models、模型和价格。
• 不要替用户注册、付款、充值，或者创建、吊销 key。这些由用户在控制台中完成。
• 不要在未询问的情况下覆盖用户用于其他工作的现有 Anthropic 或 OpenAI 配置。只修改任务需要的部分。
• 不要循环重试 402，也不要只为了测试配置而发送大请求或长请求。
• 不要依赖 Message Batches、Files API、在 Anthropic 侧运行的服务端工具（网页搜索、代码执行）或 MCP connector：EZAT Router 不提供这些功能。

机器可读的文档复制链接

只读取你需要的页面。价格和模型列表会变化；需要时再获取，不要保留一份副本。