主题
追踪和访问控制
了解网关追踪数据落在哪里，以及谁可以查看和配置什么。
NOTE
LLM Gateway 处于 beta 阶段。
通过 LLM Gateway 的每次调用都会被追踪到 LangSmith，策略违规会在 LangSmith Engine 中显示以供分类处理。
NOTE
网关追踪会为每次调用记录元数据（token 计数、策略结果、调用方身份）。默认情况下不会记录输入和输出内容，没有内容的追踪不会计入你的 LangSmith 追踪配额。只有当你通过数据策略明确启用内容记录时，才会记录内容并产生相关计费。
网关追踪出现的位置
默认情况下，所有组织的内容追踪均已关闭。开启内容追踪后，经由网关代理的调用会被追踪到与调用方 API 密钥关联的工作区中名为 gateway 的项目，以及一个在 UI 中隔离流量的按调用方项目。使用工作区 API 密钥进行身份验证的调用方会得到 gateway/short-api-key/<short_key>/api-key-id/<api_key_id>；使用 bearer token 且没有工作区 API 密钥的调用方会得到 gateway/user/<obfuscated_email>/ls_user_id/<ls_user_id>。
追踪元数据
通过网关代理的调用可以通过其落入的项目以及附加到其 span 的元数据与直接 LLM 调用区分开来：
- 网关项目： 所有网关流量都会写入每个工作区中名为
gateway的项目，并为每个调用方保留副本以隔离 UI。按项目（或按langsmith.metadata.gateway.*span 属性是否存在）筛选以查找网关代理调用。 - 策略评估结果： 每个网关 span 都会通过
langsmith.metadata.gateway.policy.matched_ids/_names、passed_ids/_names和violated_ids/_names记录评估了哪些策略及其结果，因此通过和阻止都会被捕获。 - Guard 规则匹配： 当脱敏策略适用时，guard 流水线会生成一个
rule_id → count映射，作为policy.matched_rules、passed_rules和violated_rules标记到 span 上。这些是规则 ID，不是 PII 或密钥类别标签。 - 成本数据： token 计数和成本会内联计算，并输入到支出上限策略所依据的同一个支出累加器。
追踪内容
追踪内容（请求和响应正文）默认关闭。没有内容的追踪不会计入你的 LangSmith 追踪配额。通过数据策略开启内容记录，该策略适用于通过网关发出且匹配策略范围的任何追踪。匹配内容记录数据策略的追踪会计入你计划的追踪量。
LangSmith Engine 集成
当治理策略触发时（例如达到支出限制、检测并脱敏 PII，或捕获密钥），该事件会作为元数据记录在追踪上。这些策略违规会在 LangSmith Engine 中显示为问题。
在 Engine 问题中，你可以：
- 查看违规： 哪个策略触发，阻止或脱敏了什么。
- 点击进入追踪： 准确查看策略触发时 agent 在做什么。
- 诊断根因： 是重试循环消耗预算、用户将凭据粘贴到提示中，还是合法工作负载超出其上限等。
- 采取行动： 更新 agent 配置、调整策略或上报。
审计日志
网关记录两类事件：
| 类别 | 记录内容 |
|---|---|
| 管理变更 | 策略的创建、修改和删除。与网关访问相关的角色和权限更改。 |
| 网关调用 | 每次代理调用，包括调用方身份和匹配的策略 ID。 |
权限
所需权限
| 操作 | 所需权限 | 默认拥有者 |
|---|---|---|
| 通过网关发起调用 | gateway:invoke + workspaces:read | 仅 WORKSPACE_ADMIN |
| 创建、编辑或删除策略 | organization:manage | 组织管理员 |
| 查看网关追踪 | projects:read + runs:read | WORKSPACE_ADMIN、WORKSPACE_USER、WORKSPACE_VIEWER |
| 查看审计日志 | organization:manage | 组织管理员 |
内置的 WORKSPACE_USER 和 WORKSPACE_VIEWER 角色不包含 gateway:invoke，且无法编辑。要在不授予完整工作区管理员权限的情况下授予网关访问权限，请创建一个包含 gateway:invoke 和 workspaces:read 的自定义工作区角色（需要启用 RBAC 的计划）。有关说明，请参阅管理员设置。
API 密钥作用域
始终为网关使用工作区作用域的 API 密钥。不支持使用组织作用域的密钥调用网关。
集中管理提供程序凭据
网关将提供程序 API 密钥集中存储在 LangSmith 工作区密钥中。个人开发人员和 agent 使用其 LangSmith API 密钥进行身份验证，永远不需要直接访问提供程序密钥。
这意味着：
- 凭据控制： 提供程序密钥集中在一处，由管理员管理。撤销访问权限意味着撤销 LangSmith API 密钥，而不是查找分散的提供程序密钥副本。
- 策略执行： 由于所有调用都流经网关，策略会得到一致执行。只要开发人员无法单独访问提供程序密钥，就无法通过直接调用提供程序来绕过成本限制。
对于 Claude Code Plus 和 Max 用户，所有组织都可以使用 Anthropic OAuth 直通。调用方发送工作区作用域的 LangSmith API 密钥用于网关身份验证，并发送 Anthropic OAuth bearer 用于提供程序身份验证。网关权限、策略和追踪仍然适用，而 OAuth bearer 仅转发给 Anthropic，网关不会加载工作区的 ANTHROPIC_API_KEY。Anthropic 将这些调用计入用户的 Claude 订阅。有关配置说明，请参阅设置编码 agent。
限制追踪可见性
网关追踪会作为运行写入工作区项目，并遵循 LangSmith 的标准工作区成员资格模型。工作区中任何拥有 runs:read（以及查看项目本身所需的 projects:read）的人都可以查看该工作区网关项目中的追踪。内置角色 WORKSPACE_ADMIN、WORKSPACE_USER 和 WORKSPACE_VIEWER 默认都包含这两个权限。
如果你需要限制谁可以查看网关追踪，有两种选择：
- 独立工作区（适用于任何计划）：创建一个成员受限的工作区，以及另一个供开发人员编码 agent 使用、成员范围更广的工作区。每个工作区都有自己的提供程序密钥和追踪项目。
- 项目级访问策略（需要企业计划）：编写 ABAC 策略，将网关项目上的
projects:read和runs:read限制为特定用户或角色。