使用 Cloudflare Access 保护你的 gateway,使用户在发送请求之前通过身份提供商进行身份验证。将 AI Gateway 置于 Access 之后,即可对 AI 流量实施基于身份的控制:由你决定谁可以访问 gateway,将每个请求与已验证用户关联,并按用户治理用量,而无需自行构建身份验证层,也无需从客户端应用传递用户 ID。
要将 AI Gateway 置于 Access 之后,必须先为 gateway 设置自定义域名,并且账户已启用 Cloudflare Access。
当发往自定义域名的请求包含有效的 Cloudflare Access JWT 时,AI Gateway 将该 Access JWT 作为请求凭据接受。该请求无需再发送 AI Gateway 令牌。
AI Gateway 还会将已验证的 Access 用户 ID 作为 cf.user_id 添加到请求元数据。该值是 Access JWT 的 sub 声明,而不是用户的电子邮件地址。随后你可以按已认证用户筛选日志、分析和支出。
在将请求转发到上游提供商之前,AI Gateway 会移除仅用于 Cloudflare 的凭据,例如 Access JWT 和 AI Gateway 授权标头。
自定义域名一旦受 Access 保护,发往该域名的每个请求都必须通过 Access 策略。仅包含 AI Gateway 令牌、没有有效 Access 令牌的请求会在到达 gateway 之前被 Access 阻止。请更新现有集成,改为通过 Access 进行身份验证;或继续将使用 gateway 令牌的流量发送到默认的 gateway.ai.cloudflare.com 端点,该端点不受 Access 保护。
- 为要保护的 gateway 设置自定义域名。
- 在 Cloudflare 仪表板 ↗中,前往 AI > AI Gateway。
- 选择已配置自定义域名的 gateway。
- 前往 Access 选项卡,并在该 gateway 上设置 Cloudflare Access。
- 添加 Access 策略,定义哪些用户可以调用该 gateway。
从 Access 选项卡设置 Access 会为你配置 Access 应用,因此编码智能体和其他非浏览器客户端可以通过将 Access 令牌作为 bearer token 发送来进行身份验证。
设置完成后,用户通过 Access 身份验证后即可向自定义域名发送请求。带有有效 Access 用户主体的请求会在 AI Gateway 元数据中包含 cf.user_id。
用户向 Access 完成身份验证后,向自定义域名发送请求,路径中无需包含账户 ID 或 gateway ID:
cloudflared access curl https://ai.example.com/openai/v1/chat/completions -s \
--json '{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "What is Cloudflare?"
}
]
}'每个请求都必须携带 Access 令牌。浏览器在登录后会自动以 cookie 附加该令牌。其他客户端必须显式发送。cloudflared access curl 会使用客户端设备上的 cloudflared 为命令行请求处理此事。
以下请求通过 OpenAI 兼容端点运行 Workers AI 模型:
cloudflared access curl https://ai.example.com/compat/chat/completions -s \\
--json '{
"model": "workers-ai/@cf/meta/llama-3.1-8b-instruct-fast",
"messages": [
{"role": "user", "content": "What should I buy for a summer flash sale?"}
]
}'对于编码智能体,请参阅 编码智能体 下各智能体的设置说明,例如 Claude Code 和 OpenAI Codex。
- 仅当 AI Gateway 收到带有非空用户主体的有效 Access JWT 时,才会添加
cf.user_id。 - 服务令牌(service token)请求不包含
cf.user_id,因为它们不代表单个 Access 用户。 - 你不能提供以
cf.开头的元数据键。这些键是保留的,不会被保存。