> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexinference.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 代理密钥

> 为无法按请求设置截止时间的工具创建包含截止时间的密钥。

大多数工具会构建自己的请求正文。它们不提供放置 `start_within` 的位置，并且每个没有 `start_within` 的请求都会返回 [`400 missing_start_within`](/zh/errors#missing_start_within) 错误。

代理密钥解决了这个问题。它本身包含截止时间，因此工具发出的每个请求都将根据该截止时间进行路由。

## 创建密钥

1. 打开 [仪表盘](https://www.flexinference.com/dashboard)，然后前往 **API**，再点击 **FlexInference keys**。
2. 点击 **Create agent key**。普通的 **Create key** 按钮创建的密钥不包含截止时间。
3. 为密钥命名。名称是可选的，仅用于帮助您以后查找。
4. 选择截止时间。**Flex race** 预先选中，这也是代理密钥存在的原因。
5. 如果您选择了 **Flex race**，请设置持续时间。输入任意时长，从 5 秒到 10 分钟，或者快速选择一个。
6. 点击创建，然后复制密钥。仪表盘只会显示一次。

在密钥列表上使用 **Agent keys only** 筛选器可以再次找到该密钥。行上的策略芯片会显示其包含的内容。

## 各截止时间选项的作用

| 选项            | Wire value | 发生的情况                      |
| ------------- | ---------- | -------------------------- |
| **Flex race** | a duration | 在该持续时间内尝试更便宜的层级，然后回退到标准层级。 |
| **Standard**  | `default`  | 提供标准层级服务。适用于所有模型和所有路由。     |
| **Priority**  | `priority` | 更早启动，成本更高。当用户等待响应时值得使用。    |
| **Auto**      | `auto`     | 让提供商选择。不适用于 Gemini 模型。     |

**Flex race** 成本更低，启动时间更晚。您会在交互式循环中感受到这种延迟，因此该层级适合您坐着观察的工具。

<Note>
  **Priority** 和 **Auto** 需要 BYOK 组织。[Managed
  Keys](/zh/billing) 不提供这两个层级，因此任何使用托管提供商的组织在创建时都会因 `400
      invalid_key_defaults` 而被拒绝。拒绝也包括持续时间的回退层级。
  请选择 **Standard** 或 **Flex race**。
</Note>

## 密钥携带的内容

一个密钥最多可以存储三个字段。

* `start_within`: 持续时间或层级名称。始终设置。
* `on_no_flex`: 持续时间回退到的层级。仪表盘始终存储 `default` 且从不询问。只有 API 允许您选择 `priority`。
* `retry`: 一个 `count`，从 1 到 5，可选 `backoff` 和 `jitter`。除非您要求，否则不设置。

除非有特殊原因，否则请勿修改 `retry`。大多数代理会自行重试，并且两者会叠加。每次客户端尝试都会消耗完整的服务器端预算。

## 请求始终优先

我们会将存储的字段填充到任何没有该字段的传入请求中。我们绝不会替换请求发送的值。

即使发送的值是错误的，这条规则也适用。显式错误的 `start_within` 仍然会返回 `400 invalid_start_within`。密钥默认值用于您未发送的字段，绝不会用于您发送错误字段。

我们填充的每个响应都附带 `x-flexinference-defaults-applied` 标头，列出已填充的字段。发送了自己截止时间的请求不会收到此标头。

## 密钥持续时间在请求持续时间失败时回退

请求正文中针对 `claude-*` 模型的持续时间会与 Claude 更便宜的层级竞争。有三条规则决定：托管密钥、无流式传输以及三分钟或更长时间。违反其中任何一条，请求就会失败，第一个违规会返回 [`400 flex_unsupported_for_anthropic`](/zh/errors#flex_unsupported_for_anthropic)。请参阅 [Claude durations need a longer window](/zh/deadline-routing)。

密钥上的持续时间会回退。它会运行 `on_no_flex` 层级，因此密钥始终有响应。这种回退是密钥从不与 Claude 更便宜的层级竞争的原因，无论是否使用托管密钥：截止时间在考虑竞争之前会解析为您的层级。

这种回退仅涵盖模型。您自己的请求造成的冲突仍然会失败。固定云路由会造成这种情况，因为云路由只运行标准层级。请参阅 [`key_default_not_applicable`](/zh/errors#key_default_not_applicable)。

## 编辑或撤销

在密钥行上编辑截止时间。实时流量会在几秒钟内生效，并且您会保留相同的密钥。没有任何东西会重新启动，密钥也保持不变。

撤销密钥会同时清除其默认值。

## 代理密钥不适用的情况

工具需要一个基本 URL 和一个密钥字段才能访问我们。如果产品仅针对其供应商自己的订阅运行，则两者都没有，因此任何密钥都无法访问它。

## 各工具指南

| 工具                                 | 调用的接口            |
| ---------------------------------- | ---------------- |
| [Codex](/zh/coding-agents)         | Responses        |
| [Cursor](/zh/cursor)               | Chat Completions |
| [Claude Code](/zh/claude-code)     | Messages         |
| [Claude Cowork](/zh/claude-cowork) | Messages         |
| [OpenCode](/zh/opencode)           | Chat Completions |
| [OpenWork](/zh/openwork)           | Chat Completions |
| [OpenScience](/zh/openscience)     | Chat Completions |
| [OpenWorker](/zh/openworker)       | Chat Completions |
| [OpenClaw](/zh/openclaw)           | Chat Completions |

## 故障排除与常见问题

[Errors](/zh/errors) 包含我们返回的每个拒绝信息，包括其线形、原因和修复方法。每个工具指南都涵盖了该客户端特有的错误。

有一种拒绝属于代理密钥本身。

**每个请求都出现 [`400 missing_start_within`](/zh/errors#missing_start_within) 错误。** 密钥不包含截止时间，因此它是通过 **Create key** 而不是 **Create agent key** 创建的。请使用 **Create agent key** 创建一个新密钥并替换它。没有默认值创建的密钥以后无法获得默认值，因此该行不提供添加默认值的控件。

**工具是否需要知道它持有代理密钥？** 不需要。它以与任何密钥相同的方式进行身份验证，并且每个密钥都以 `flex_live_` 开头。

**一个密钥可以同时服务于工具和我的代码吗？** 可以。您的代码发送 `start_within` 并优先。工具不发送任何内容并采用密钥的截止时间。

**这会产生什么费用？** 我们会运行代理发出的每个请求。在您自己的提供商密钥上，这不会在这里产生任何费用，您的提供商会收取 token 费用。在 [Managed Keys](/zh/billing) 上，每个请求都会消耗您的余额，因此请设置 **Request volume** 警报。

**为什么一台笔记本电脑达到了速率限制？** 我们对每个源 IP 地址的成功请求进行限制，涵盖其背后的所有密钥。快速循环会在达到每个密钥限制之前达到此限制。请参阅 [`rate_limit_exceeded`](/zh/errors#rate_limit_exceeded)。