> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 护栏

> 管理模型访问、Agent 行为、Session 成本、安全与路由

护栏是 Alephant 流量周围的策略与执行框架，而不是单一过滤器或单条规则。它连接模型访问策略、Agent 专属策略、Session 成本控制、安全控制，以及用于解释每次决策的日志。

使用护栏可以定义工作区、部门、成员、Virtual Key、Agent 或 Session 能够访问什么以及可以花费多少。配置保存在 Alephant 控制平面中，由相关 Gateway 和后端运行时应用最终生效的策略。

## 护栏如何协同工作

| 策略入口         | 主要作用域                  | 控制内容                                    |
| ------------ | ---------------------- | --------------------------------------- |
| LLM 策略       | 工作区、部门、成员和 Virtual Key | 模型访问、预算、请求与 Token 限制、安全控制和路由行为          |
| Agent 策略     | 工作区、部门或单个 Agent 绑定     | 允许的模型、Agent 预算、运行限制、重试行为、追踪要求和工具权限      |
| Session 成本控制 | 共享同一 `session_id` 的请求  | 单 Session 预算、累计成本、突发保护、模型降级和 Agent 专属覆盖 |

护栏与 Endpoint Policy、Spend Policy 相互补充，但它们管理不同的运行时边界。Endpoint Policy 控制已发布的端点，Spend Policy 控制 Agent 对外支付。

## LLM 策略

LLM 策略管理通过 Alephant Virtual Key 发起的调用。在 Dashboard 中打开 **Control → LLM Policy**，即可查看当前工作区、套餐和部署模式支持的控制项。

### 访问控制

访问控制决定哪些调用方和资源可以使用 Gateway：

* **Model Allowlist** 将请求限制为已批准的模型。
* **IP/CIDR Allowlist** 将 Gateway 访问限制为已批准的网络范围。
* **Department Key Access** 控制哪些部门可以使用指定 Master Key。

模型和密钥访问范围应与工作负载保持一致。Fallback 或优化规则不能绕过访问限制。

### 用量限制

用量限制用于保护预算和上游容量：

* 按月或按季度计算的工作区预算、告警阈值和超限动作
* Daily Hard Stop 和 Monthly Spend Alert
* RPM、RPH 和 Burst Allowance 等自定义请求限制
* 并发请求限制和 Token 限制
* 面向 Virtual Key 的成员预算上限
* 部门级预算与速率覆盖

部分控制项始终启用，部分可以开启或关闭，另一些需要特定套餐。Dashboard 会显示当前状态和可用性，不应把所有列出的控制项都视为已经生效。

### 安全与合规

Enterprise 工作区可以提供更多控制：

* 基于时间的访问窗口
* 支持 block、redact 或 alert 行为的 PII 检测
* 针对 API 请求与策略动作的审计日志

具体可用性取决于工作区套餐和部署模式。在生产环境依赖某项控制前，应先检查页面显示的策略状态。

### 智能路由与优化

与路由相关的护栏可以包括模型 Fallback、Semantic Caching、Provider Key 负载均衡和成本感知路由。这些控制还取决于已配置的路由模式、Managed Credits、Provider 访问，以及工作区使用 Managed Routing 还是仅使用 BYO Key。

不要因为某个路由选项可见就假设它已生效。请在 Dashboard 中检查状态，并参阅[路由优化](/ai-gateway/routing-optimization)了解路由专属行为。

## Agent 策略

Agent 策略用于定义可复用的策略配置，并将其绑定到工作区、部门或单个 Agent。在 **Control → Agent Policy** 中可以创建、编辑、启用、停用和绑定策略。

| 策略区域 | 可配置值                                             |
| ---- | ------------------------------------------------ |
| 模型访问 | 所有模型、Provider 默认模型或选定模型                          |
| 预算   | 月度预算、单次运行最大成本，以及 alert 或 block 动作                |
| 运行时  | Runtime mode、是否要求 Run tracking、最大请求数、最长持续时间和重试次数 |
| 工具   | 所有工具、选定工具或未配置                                    |
| 绑定   | 工作区默认、部门、单个 Agent 或混合作用域                         |

Agent 策略比通用的工作区控制目录更具体：它随 Agent 的运行生效，并提供用于归因和策略评估的 Agent 上下文。已配置字段表示期望的策略状态；该字段是否执行以及如何执行，仍以后端与 Gateway 运行态为准。

## Session 成本控制

Session 成本控制管理共享同一 `session_id` 的一组相关模型调用。

| 控制项                    | 用途                                |
| ---------------------- | --------------------------------- |
| C1 — Budget Cap        | 设置单个 Session 允许的最大成本，并选择当前支持的拦截动作 |
| C2 — Cost Accumulation | 跨调用累计成本，并为 Session 关联阈值动作         |
| C3 — Rate Limiting     | 防止 Session 出现失控循环和请求突发            |
| C4 — Model Downgrade   | 在接近成本阈值时，从一个已配置模型切换到更便宜的已配置模型     |
| Per-Agent Overrides    | 为选定 Agent 覆盖当前支持的工作区默认值           |

Dashboard 将预算上限拒绝描述为 HTTP `402`，将速率限制拒绝描述为 HTTP `429`。精确响应体和支持的拦截动作取决于已部署的 Gateway 版本，因此应用应处理 HTTP 状态并检查实际返回错误，而不是依赖未形成合同的错误字符串。

为每个请求附加 Session 和 Agent 上下文：

```bash
curl "$ALEPHANT_GATEWAY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "alephant-session-id: sess_support_8421" \
  -H "Alephant-Agent-Id: agt_support_bot" \
  -H "Alephant-Run-Id: run_support_8421_001" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Classify this support request." }
    ]
  }'
```

将 `ALEPHANT_GATEWAY_BASE_URL` 设置为 Dashboard 中显示的 Gateway Base URL。Alephant Cloud 默认使用 `https://ai.alephant.io/v1`；private deployment 可以提供不同的运行时地址。

## 配置并验证策略

1. 添加 Provider Key，并创建用于发送 Gateway 流量的 Virtual Key。
2. 打开 **Control → LLM Policy** 或 **Control → Agent Policy**。
3. 配置策略、作用域、状态以及当前支持的覆盖项。
4. 通过已配置的 Gateway Base URL 发起请求，并在适用时携带 Agent、Run 和 Session 标识。
5. 在 Request Logs 中检查实际 Provider、模型、状态、Token 用量、成本和策略元数据。
6. 在 Sessions 中检查累计成本、拦截、模型变化和 Per-Agent 行为。
7. 在 Audit Logs 中检查工作区暴露的配置和执行事件。

当多个作用域同时适用时，应在目标部署中验证最终结果后再投入生产。本页不为所有策略类型定义统一优先级；应以对应策略的后端和 Gateway 合同为准。

## 可用性与执行边界

Dashboard 使用以下状态：

| 状态                        | 含义                |
| ------------------------- | ----------------- |
| Always On                 | 当前工作区无法停用的基础控制    |
| Active / Off              | 已持久化并处于启用或停用状态的控制 |
| 套餐限制                      | 控制项可见，但需要其他套餐     |
| Coming Soon / unavailable | 当前产品或运行模式暂不可用     |

应分别检查配置状态、Gateway 执行结果和可观测记录。表单保存成功只能确认控制平面配置；请求结果及其日志才能确认运行时行为。

## 相关页面

* [Provider 路由](/ai-gateway/provider-routing)
* [路由优化](/ai-gateway/routing-optimization)
* [Session](/ai-gateway/session)
* [策略与规则](/docs/overview/security-compliance/policies-rules)
* [Agent 运行追踪](/docs/overview/core-concepts/agent-run-tracing)