---
title: "智能体控制：限定范围的密钥、支出限额与安全重试"
description: "Bird 如何限制 AI 智能体的操作范围：限定范围的 API 密钥、幂等发送、默认拒绝的 SMS 目的地、按国家设置的每日支出限额，以及预付费钱包。"
canonical: "https://bird.com/zh-sg/wendang/ai/agent-controls"
---

# 智能体控制：限定范围的密钥、支出限额与安全重试

通过 Bird 发送消息的智能体持有凭据，并消耗你的余额。有五项控制可限制它的操作范围。第一项是凭据本身。其余四项只有在智能体的凭据无法修改它们时才有效，因此请先从凭据入手。

| 控制项                                         | 限制的内容                    | 达到限制时调用方收到的结果                         | 设置者                             |
| ---------------------------------------------- | ----------------------------- | -------------------------------------------------- | ---------------------------------- |
| [凭据](#选择智能体持有的凭据)                  | 智能体可以调用的操作          | `403`                                              | 创建密钥或批准登录的人             |
| [幂等键](#重试发送而不重复发送)                | 请求重试时产生的重复发送      | 重放的原始响应                                     | 调用方，在每个请求中设置           |
| [SMS 目的地允许列表](#逐个允许-sms-目的地国家) | SMS API 发送可以到达的国家    | `422 SMSDestinationNotEnabled`                     | 具有 `sms_management` 写权限的凭据 |
| [SMS 每日支出上限](#按国家限制每日-sms-支出)   | 一天内发往单个国家的 SMS 支出 | `422 SMSDestinationDailySpendExceeded`             | 具有 `sms_management` 写权限的凭据 |
| [预付费钱包](#用预付费钱包限制总花费)          | 按量付费的支出                | SMS 和 WhatsApp 返回 `402`。付费邮件在发送后扣费。 | 组织所有者或账单管理员             |

本页的目的地允许列表和每日支出限额适用于 SMS。[Verify](/docs/guides/verify/destinations) 和 [Voice](/docs/guides/voice/destinations) 各有自己的目的地设置，且初始状态不同。Email 和 WhatsApp 没有目的地允许列表，也没有每日支出限额，因此在这些渠道上，限制智能体的是凭据的权限范围和钱包。

## 选择智能体持有的凭据

智能体调用 Bird 时使用两种凭据之一。两者的可访问范围不同。

- **API 密钥**（`bk_`）带有你授予它的权限范围，并归属于一个工作区。它不能签发其他密钥，也无法访问组织账单、成员或设置。你的代码将其作为 bearer 令牌发送。设置了 `BIRD_API_KEY` 中的密钥时，CLI 和本地 MCP 服务器（`bird mcp`）会优先使用该密钥，而不是已保存的登录凭据。
- **OAuth 令牌**（`bt_`）是用户登录后 CLI 和 MCP 服务器持有的凭据。它带有该用户批准的权限，且永远不会超出该用户自身拥有的权限。这些权限可能包括 `api_keys` 写入、`sms_management` 写入和组织账单。持有此类令牌的智能体可以签发密钥、启用国家/地区，并提高本页所述的限额。

OAuth 令牌的权限大小取决于它的创建方式：

- **`bird auth login`** 请求只读访问权限。`--scope` 请求你指定的权限集，`--yolo` 请求你能够委派的所有权限。你需要在浏览器中批准最终结果。
- **托管的 MCP 客户端**可以请求你能够委派的所有权限。你可以在授权同意页面上选择要授予哪些权限。批准前，请取消勾选智能体不需要的权限。
- **[自助注册](/docs/ai/self-serve-signup)** 没有授权同意页面。它创建的凭据拥有新组织所有者可委派的全部权限，包括组织账单权限。

对于无人值守运行的代理，请创建一个限定范围的 API 密钥并交给代理使用。权限更广的登录凭据留给负责配置工作区的人。你可以在 **Profile** > [**Connected apps**](https://bird.com/dashboard/profile/connected-apps) 下撤销某个工具的登录。[API 密钥与 OAuth 令牌](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) 比较了这两类凭据。

## 为每个密钥限定其所需的产品范围

API 密钥带有一组作用域，每个作用域对应一个产品领域，级别为 `read` 或 `write`。只用于发送 SMS 的密钥持有 `sms:write`。超出密钥作用域的请求会返回 `403`，因此即使密钥泄露或被滥用，也只能访问你授予它的内容。

无论作用域如何，密钥始终具有以下三个特性：

- **密钥不能签发其他密钥。** 签发和轮换密钥需要 `api_keys:write`，而 API 密钥无法获得该权限。这一权限须由人在控制台会话中，或在 CLI 或 MCP 登录时批准。
- **密钥仅限于其所属工作区。** 它无法访问账单、组织成员或组织设置。
- **密钥可以设置过期时间。** 创建时设置 `expires_at`，过了该时刻后密钥会返回 `401`。你可以随时轮换或撤销密钥。

你可以在控制台或终端中创建密钥。CLI 登录只能为密钥授予该登录本身持有的作用域，因此下面的示例除了 `api_keys:write` 之外还请求了 `sms:write`：

```bash
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write
```

[身份验证与 API 密钥](/docs/guides/authentication) 列出了作用域表，并介绍了过期、轮换和撤销。

## 重试发送而不重复发送

代理如果没有收到响应，就无法判断请求是否已被接受。每次计划发送时，在 `Idempotency-Key` 请求头中附上一个唯一值；结果未知时，用同一个键重复同一请求。Bird 会返回原始响应，且消息只被接受一次。重放的响应带有 `Idempotency-Replay: true`。

保证的是：在保留期内，每个密钥只会有一次操作被接受。该保证仅覆盖 API 对请求的接受。消息是否送达手机另行报告，以消息状态及其事件为准。

SDK 会为每个修改性调用生成一个密钥，并在自动重试时复用该密钥。使用 CLI 时，请传入 `--idempotency-key`。[幂等性](/docs/guides/idempotency)介绍了密钥格式、保留期，以及同一密钥用于不同请求时的处理方式。

## 逐个允许 SMS 目的地国家

SMS 目的地允许列表默认拒绝。通过 SMS API 发送的消息只能发往列表中已启用的国家。发往其他国家的消息会在解析发送方之前被拒绝并返回 `422 SMSDestinationNotEnabled`，因此不会有消息被接受。如果代理将消息发往意外的国家，请求会被拒绝。此规则适用于从您自己的代码、从 `bird sms send` 以及从 `sms_send` MCP 工具发出的消息。

验证码不受此列表约束。Verify 在 [Verify destinations](/docs/guides/verify/destinations) 下有自己的列表，所有国家初始均为启用状态。因此，拥有 `verify` 写权限的凭据可以通过 SMS 向此允许列表所阻止的国家发送验证码。如果代理持有 `verify`，请在该页面上同样关闭您不提供服务的国家。

您可以在 [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations) 下、使用 `bird sms destinations update`，或使用 `sms_destinations_update` MCP 工具启用国家：

```bash
bird sms destinations update --destination NL=true
```

修改允许列表需要 `write` 级别的 `sms_management` 作用域。仅持有 `sms` 的凭据可以向已启用的国家发送消息，但不能启用更多国家。请为负责发送的代理提供 `sms`，并将 `sms_management` 留给负责配置工作区的凭据。

[发送 SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) 说明了允许列表的初始状态以及本国的添加方式。

## 按国家限制每日 SMS 支出

每个目的地国家都可以设置每日支出上限，以您钱包的币种计算。当天发往该国家的支出达到上限后，新消息会被拒绝并返回 `422 SMSDestinationDailySpendExceeded`，直到 UTC 午夜。上限设为零即阻止该国家。

通过 SMS 发送的验证码计入该上限。达到上限后，Verify 会停止通过 SMS 向该国家发送验证码，并尝试该国家启用的下一个渠道。如果没有剩余渠道，验证将失败并返回 `422 NoAvailableChannel`。

上限的设置位置与允许列表相同，共三处。以下命令在钱包币种为 EUR 的工作区中启用荷兰，并将其上限设为每天 25 EUR：

```bash
bird sms destinations update --destination "NL=true;25EUR"
```

该限额并不精确。修改限额后，最多需要一分钟才会在发送中生效。花费在消息计费时才计入，因此已接受的消息可能使当天总额超出限额，超出部分为这些消息的费用。设定限额时请预留这部分余量。`bird sms destinations list` 会显示每个国家的限额及当天已用额度。

设置限额所需的 `sms_management` 写入权限与允许列表相同，因此仅持有 `sms` 的凭据无法提高自己的限额。完整规则请参阅[发送 SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country)。

## 用预付费钱包限制总花费

按用量付费的发送从组织的预付费钱包中扣款。余额不足以支付一次发送时会发生什么，取决于渠道：

- **SMS 和 WhatsApp** 会在 API 处被拒绝，并返回 `402`。如果消息已被接受但扣费失败，该消息以 `rejected` 结束，且不计费。
- **付费 Email 套餐中的邮件**在发送后不久扣费，因此余额可能短暂低于零。钱包没有余额或信用额度后，新邮件会被拒绝并返回 `402`，直到充值为止。
- **投递时产生的费用**如果余额无法支付，则会跳过该费用，消息仍会送达收件人。

钱包余额耗尽会阻止后续花费，但不会将花费精确限制在余额以内。充值时请为接受后才扣费的发送预留余量。如果开启了自动充值，余额低于你设定的阈值时，钱包会从已保存的银行卡自动充值，此时余额本身不再限制代理能花费的金额。这些规则以[账单与用量](/docs/guides/billing-and-usage#the-wallet)为准。

账单操作需要组织的账单权限 `org:billing`。API 密钥无法持有该权限，因此任何密钥都不能为钱包充值、更改套餐或读取用量。如果批准登录的人持有该权限并授予组织权限（组织所有者可以这样做），OAuth 令牌就能持有它。自助注册生成的凭据从一开始就持有该权限。为无人值守的代理提供限定范围的密钥，充值操作就仍由预算负责人掌控。

[支付方式与钱包](/docs/knowledge-base/billing/payment-methods-wallet)介绍充值、自动充值和余额不足提醒。

## 后续步骤

- [自助注册](/docs/ai/self-serve-signup)：在终端中创建代理使用的账户。
- [身份验证与 API 密钥](/docs/guides/authentication)：作用域、过期、轮换和吊销。
- [速率限制](/docs/guides/rate-limits)：适用于组织内所有密钥的请求限制。
- [为智能体分配专属电话号码和收件箱](/docs/ai/agent-number-and-inbox)：智能体用于发送和接收消息的身份。

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)
