---
outline: 2
head:
  - - meta
    - name: description
      content: OneGateway 常见问题，涵盖产品定位、模型接入、API Key、权限、额度与计费、供应商路由、语义缓存、安全护栏及调用排障。
---

# 常见问题（FAQ）

本文面向使用 OneGateway 的成员（包括接入应用的开发者）和管理员，解答接入、日常使用和管理中的常见问题。首次调用可先阅读[快速开始](/guide/getting-started)；具体菜单和可用能力取决于当前环境的配置与角色权限。

| 你想了解 | 查看 |
| --- | --- |
| 产品用途、部署方式与数据流向 | [产品与部署](#product) |
| 应用如何接入、模型如何选择 | [接入与模型](#integration) |
| 密钥、角色、部门和分组定价的区别 | [API Keys 与权限](#access) |
| 额度不足、周期重置、兑换与费用 | [额度与计费](#billing) |
| 供应商接入、主备切换、配置生效 | [供应商与路由](#routing) |
| `og-auto`、按复杂度选模型、模型切换 | [智能路由](#intelligent-routing) |
| 缓存是否省钱、为什么没命中 | [语义缓存](#cache) |
| 内容拦截、脱敏与流式响应 | [安全护栏](#guardrails) |
| 日志延迟、调用失败、问题反馈 | [日志与排障](#troubleshooting) |

## 产品与部署 {#product}

### OneGateway 解决什么问题？ {#product-purpose}

OneGateway 是面向企业的统一 AI 网关与 Token 管理平台。员工、业务应用和 AI Agent 通过统一入口调用模型，管理员集中管理供应商连接、模型权限、API Key、消费额度和调用记录。

它提供模型接入与治理能力，模型回答仍由接入的上游服务生成。核心能力见[简介](/guide/introduction)。

### 已经有模型供应商账号，为什么还需要 OneGateway？ {#existing-provider-accounts}

企业可以将上游密钥集中托管，为不同成员和应用分别发放 OneGateway API Key，避免在各个应用中分散维护供应商密钥。同时，可以统一设置模型权限和消费上限，按成员、部门、模型查看费用，并为同一模型配置多个供应商以支持分流和故障重试。

### 支持哪些部署方式？业务数据会发到哪里？ {#deployment-data-flow}

支持 SaaS 和混合部署。SaaS 使用平台提供的云端服务；混合部署在企业内网部署专属 Token Gate，适合接入内网模型或管理企业内部的调用流量。

混合部署调用内网模型时，请求与响应内容可以保留在企业网络内，配置、额度和用量等管理数据与云端控制台同步。**实际数据流向还取决于依赖服务的位置**：调用外部模型会向该模型服务发送请求；启用外部 Embedding、安全审核模型或判定服务时，相关文本也会发送给这些服务。部署时应一并确认这些依赖的位置。参阅[部署模式](/guide/introduction#部署模式)。

### 控制台和网关分别负责什么？应用应该访问哪个地址？ {#console-and-gateway}

控制台负责管理用户、权限、配置、报表和审计；网关（Token Gate）负责实时请求处理，包括协议适配、路由、额度校验与扣减，以及已启用的插件处理。

日常管理统一在 OneGateway 控制台完成，应用使用 API Keys 页面提供的 **API 地址**。

## 接入与模型 {#integration}

### 接入应用需要准备什么？已有应用要改多少代码？ {#integration-requirements}

准备三个值：**API 地址、OneGateway API Key、模型 ID**。前两个从 API Keys 页面获取，模型 ID 从可用模型页面复制。

已有应用使用兼容的接口格式时，通常只需替换地址、密钥和模型 ID。涉及供应商专有参数或功能时，还需验证所选模型和接入类型是否支持。完整调用示例见[快速开始](/guide/getting-started)。

### API 地址要不要加 `/v1`？模型名称该填哪个？ {#api-url-and-model-id}

请求地址该填基础地址还是完整地址，取决于你使用的客户端。以快速开始中的 OpenAI 格式为例：用 SDK 时填 Base URL（`https://your-api-endpoint/v1`）；直接发送聊天 HTTP 请求时填完整地址（`https://your-api-endpoint/v1/chat/completions`）。有些客户端会自动补全路径，请确认客户端的处理方式，避免重复添加 `/v1`。

请求的 `model` 必须使用[可用模型](/user/models)中的 **模型 ID**，不要填写卡片上的显示名，也不要直接填写供应商名称。管理员提供的[虚拟模型](#virtual-model)名（如 `og-auto`）是例外，不在可用模型中也可以直接使用。

如果管理员配置了模型名称映射，[日志](/user/usage#查看单条调用的明细)中的上游实际模型可能与请求的模型 ID 不同。名称不同本身不代表调用出错，可请管理员核对该供应商的映射配置。

### 可以接入企业自建模型吗？所有模型都支持同样的功能吗？ {#self-hosted-models}

可以接入协议兼容的企业自建模型，前提是网关能够访问其服务地址，且管理员配置了匹配的接入类型、凭据和模型。

统一入口不会改变模型本身的能力。上下文长度、工具调用、图片、音频和推理等功能仍取决于目标模型与接入协议。模型定义中的上下文和价格字段用于描述及计费，修改它们不会扩展模型能力。参阅[供应商与模型](/admin/providers-and-models)。

### 为什么同事能看到或调用某个模型，我却不能？ {#model-access}

不同成员的模型范围可能不同。先核对自己的可用模型，再检查 API Key 的可用模型限制。管理员还需确认目标模型有处于启用状态、并已选择该密钥分组定价的供应商。

**在页面看到模型，不代表每一把 API Key 都能调用它**；密钥上的限制可以进一步收窄范围。授权关系见[分组定价与 API Key](/admin/providers-and-models#为-api-key-指定分组定价)。

### 模型状态是灰色，或价格显示 `--`，是什么意思？ {#model-status}

灰色状态块表示对应时段没有调用记录或监控数据，不能直接据此判断模型不可用。状态展示的是模型整体的近期调用情况，也不保证你的下一次请求一定成功。

价格显示 `--` 表示该价格项暂未配置，不代表调用免费。按次计费的模型，输出价格显示 `—`。具体字段见[看懂模型卡片](/user/models#看懂模型卡片)。

## API Keys 与权限 {#access}

### OneGateway API Key 和上游供应商密钥有什么区别？ {#api-key-types}

上游密钥由管理员在供应商接入配置中维护，用于网关访问模型服务；OneGateway API Key 是成员或应用访问网关的凭证，归属于具体成员，并受平台权限与额度规则约束。

可以为不同应用分别创建 API Key，独立设置配额、有效期、可用模型和 IP 限制，便于追踪消费和停用单个应用。操作见[API Keys](/user/tokens)。

每个账号可创建的密钥数量受系统上限约束。若创建时提示数量超限，请联系管理员核对限制，并确认现有密钥是否仍被应用使用后再清理。

### API Key 显示“无限额度”“全部模型”，是否真的没有限制？ {#unlimited-key}

不是。“无限额度”只表示这把密钥没有单独的消费上限，调用仍受成员额度、账户余额和其他访问规则约束。

“全部模型”表示没有在密钥上额外设置模型白名单，仍需有启用的供应商承载目标模型。它不会授予平台上所有模型的调用权限。

### 角色、部门、分组定价分别控制什么？ {#roles-and-groups}

| 配置 | 主要作用 |
| --- | --- |
| 角色 | 控制可见菜单和允许执行的操作 |
| 部门 | 记录组织归属，用于按部门分析用量和费用 |
| 分组定价 | 决定调用适用的定价倍率 |
| API Key 限制 | 对某个应用或用途进一步限制模型、额度、有效期和来源 IP |

修改部门不会自动改变角色、分组定价或成员额度。调整用户的分组定价后，也应核对已经明确指定分组定价的 API Key。分组定价的选择和管理入口取决于部署方式与权限；由平台统一管理分组定价的环境可能不提供手工调整入口，此时应联系管理员核对适用的定价倍率。详见[分组定价](/admin/providers-and-models#分组定价)。

### API Key 泄漏或人员离职时，怎么停止调用？ {#revoke-access}

密钥疑似泄漏时：

1. 关闭该 API Key 的状态开关，保留密钥及其历史记录用于排查。
2. 创建新密钥并更新应用。
3. 确认不再需要后删除旧密钥。删除无法恢复。

人员离职时，管理员应停用账号并核对其 API Key 状态，确认配置已同步、旧凭据的请求已被拒绝。不要只通过取消额度来停用访问，因为账户可能仍有可消费的余额。

启用语义缓存时，还需分别验证原本可命中缓存的请求和需要转发上游的请求。缓存前的有效凭据校验结果默认缓存 5 分钟，不能仅凭控制台开关推断所有路径立即拒绝旧凭据，也不能把该时长当作撤销生效的承诺。若旧凭据仍能取得回答，应由管理员检查配置同步和 Token Gate 的凭据校验状态；更换应用密钥本身不代表旧凭据已失效。参阅[凭据校验与停用验证](/guide/semantic-cache#凭据校验与停用验证)、[管理 API Keys](/admin/tokens)和[维护与停用用户](/admin/users#维护与停用用户)。

### 为什么同一把 API Key 在部分机器上能用，在其他机器上不能用？ {#machine-specific-failures}

先检查密钥的 **IP 限制** 是否包含这些机器的实际出口地址；存在代理或网络地址转换时，出口地址可能与机器的内网地址不同。再核对两边的 API 地址、模型 ID、密钥是否一致，以及网络能否到达网关。

## 额度与计费 {#billing}

### 成员额度、账户余额和 API Key 配额有什么区别？ {#quota-types}

| 类型 | 来源与用途 | 是否按周期重置 |
| --- | --- | --- |
| 成员额度 | 管理员为成员分配的周期消费上限 | 是 |
| 账户余额 | 通过兑换码充值，按实际消费扣减 | 否 |
| API Key 配额 | 对单把密钥施加的额外消费上限 | 不随成员额度周期自动重置 |

这里的额度、余额和配额都是**消费金额**，不是 Token 数量；`$` 表示美元，例如 `$100` 表示 100 美元的消费额度。

调用优先消耗成员额度，额度不足时消耗账户余额；未配置成员额度时直接使用余额。与此同时，API Key 的配额限制仍独立生效。详见[额度与余额](/admin/quota#额度与余额)。

### 新账号第一次调用就提示额度不足，怎么办？ {#new-account-quota}

创建账号或 API Key 不等于已经获得消费额度。先在[个人看板](/user/my-dashboard)确认成员额度是否已配置、余额是否可用；若没有成员额度且余额为零，请管理员[分配额度](/admin/quota#分配额度)，或在环境已启用兑换码时使用有效兑换码[充值余额](/user/redemption)。

完成分配或充值后，还需核对 API Key 自身配额和配置同步状态，再重新调用；不要只根据 HTTP 状态码判断是否为额度问题。

### 成员额度用完就一定停止调用吗？为什么还有余额却提示额度不足？ {#exhausted-quota}

成员额度用完后，如果账户余额充足，仍可能继续调用。取消成员额度也不会清空余额。

反过来，即使成员额度或余额还有剩余，**单把 API Key 的配额耗尽也会阻止调用**。排查时同时检查成员额度、账户余额和密钥配额，并查看配置是否已同步；页面显示的已用金额也可能晚于实时消费。

### 额度什么时候重置？没用完的能结转吗？ {#quota-resets}

可选的重置周期以当前环境的额度配置页面为准：每周对应每周一 00:00，每月对应每月 1 日 00:00；如果页面提供每天选项，则对应每天 00:00。

重置按网关服务器的运行时区执行，不由个人电脑或组织的时区设置决定；请以控制台显示的 **下次重置** 时间为准。

上一周期未使用的成员额度不累加到下一周期，也不支持自行选择其他重置日期或时刻。兑换码充入的余额不受周期重置影响。见[周期重置与用量通知](/admin/quota#周期重置与用量通知)。

### 调高额度，会保留本周期已经使用的金额吗？ {#quota-adjustments}

不会。保存额度调整会结束原周期并建立新周期，**本周期已用金额归零**，按新设置重新计算额度和下次重置时间。

这不是在原周期剩余额度上简单追加一笔金额。当前调整入口也用于保存通知设置，因此即使只修改通知设置，保存后同样会重置周期。详见[调整与取消额度](/admin/quota#调整与取消额度)。

### 按部门分配额度，是整个部门共享一笔钱吗？新成员会自动获得额度吗？ {#department-quotas}

不是。按部门选择只是批量选人，保存后为本次选中的每位成员分别配置额度。例如，选中 10 人、每人额度 $100，表示每人各有 $100 的周期额度。

后续新加入部门的成员不会自动获得这次额度；管理员需要在“未配置”视图中找到他们并另行分配。成员调动部门后，已有额度规则不自动改变。批量保存可能部分成功，应按失败明细处理保存失败的成员，避免重复调整已成功成员。

### 为什么没有兑换码入口？兑换成功会增加成员额度吗？ {#redemption}

兑换码功能需要环境启用；组织通常选择成员额度或兑换码中的一种方式，没有入口时可在[个人看板](/user/my-dashboard)查看额度并联系管理员。

兑换成功增加的是当前登录账户的 **余额**，不会提高周期额度，也不会重置本周期已用金额。同一个兑换码只能成功兑换一次；无法兑换时，请管理员核对是否已使用、已过期、被禁用或不在适用范围。参阅[兑换码充值](/user/redemption)。

### 费用如何计算？为什么同一模型的费用不完全一样？ {#billing-calculation}

模型支持按 Token 用量或按调用次数计费。按量计费可能包含输入、输出、缓存读取、缓存创建及图片、音频等价格项，并结合适用的定价倍率计算。

相同模型的实际输入输出长度、缓存用量、定价倍率或计费配置不同，都可能造成费用差异。核对时展开[日志](/user/usage#查看单条调用的明细)，查看本次价格、用量、定价倍率和计费过程；不要只用总 Token 数乘以单一价格。

### 日志的花费显示“订阅”，是不是免费调用？ {#subscription-charge}

不是。“订阅”表示本次调用从成员的周期额度中扣减。使用兑换码余额时，花费列显示本次调用的具体金额。核对周期额度消耗可查看[个人看板](/user/my-dashboard)，核对单次计费可展开日志明细。

## 供应商与路由 {#routing}

### 供应商测试连接成功，为什么模型还是调用失败？ {#connection-test}

测试连接主要访问上游模型列表接口，用于检查连接和发现模型，并不验证每个模型都能正常生成回答，也不验证成员的调用权限。

还需检查供应商是否启用、支持模型是否正确、是否已选择对应的分组定价、API Key 是否满足限制，并发起一次实际调用。测试成功却没有可选模型时，先检查当前实例中是否存在同名模型定义。详见[测试连接并选择模型](/admin/providers-and-models#测试连接并选择模型)。

### 同一模型如何使用多个供应商？优先级和权重有什么区别？ {#routing-priority}

同一模型可由多个供应商承载。优先级数值越大越优先，同一优先级内按权重分流，较低优先级作为备用候选。

例如，同层两条供应商权重为 3 和 1，可理解为约 3/4 和 1/4 的选择概率，不保证少量请求严格按 3:1 分配。**优先级和权重属于供应商配置**，在某个模型路由视图中修改后，也会影响该供应商承载的其他模型。见[模型路由](/admin/providers-and-models#模型路由)。

### 配置了备用供应商，主供应商失败时就一定能切换成功吗？ {#failover}

不保证。切换取决于触发重试的错误、重试次数、备用供应商状态、分组定价配置及目标模型是否可用。管理员应结合实际重试策略验证，并在日志中确认最终承载请求的供应商。

切换供应商时，应用通常继续使用原来的模型 ID。

### 只创建模型定义就能调用吗？停用模型会影响什么？ {#model-definitions}

不能。模型定义维护名称、上下文、描述与价格，实际接入还需要供应商配置。管理员应把模型加入供应商的支持范围，并检查分组定价、启用状态和同步结果。

停用模型会从当前网关实例内相关供应商的支持范围中移除该模型，影响依赖它的调用；重新启用后仍需检查承载供应商和同步结果。见[模型市场](/admin/providers-and-models#模型市场)。

## 智能路由 {#intelligent-routing}

以下解答接入时的常见疑问，更多细节见[智能路由专题常见问题](/guide/intelligent-routing#常见问题)。

### `og-auto` 是什么？为什么在可用模型里找不到？ {#virtual-model}

`og-auto` 这类名称是管理员在[智能路由](/guide/intelligent-routing)中配置的**虚拟模型**：请求时写它，网关会按请求复杂度或规则改成实际的模型。虚拟模型不对应任何供应商，所以不会出现在[可用模型](/user/models)中，可以直接在请求里使用；具体有哪些虚拟模型请向管理员确认。

### 怎么知道这次请求实际用了哪个模型？按哪个模型计费？ {#routed-model}

以响应头 `og-route-model` 为准，它是路由后发给供应商的模型，计费也按这个模型，具体费用以[日志](/user/usage)中的计费明细为准。响应体里的 `model` 是供应商回报的模型名，供应商做了模型映射或使用带版本号的名称时可能不同，不能用来核对价格。调用方原本请求的模型在响应头 `og-route-requested-model` 中，只在模型被改写时出现。

### 用 `og-auto` 时返回 403 或"无权访问模型"，怎么办？ {#routing-403}

API Key 限定了可用模型时，按改写后的**实际模型**校验。把 `og-route-model` 显示的模型加进这把 API Key 的可用模型；更稳妥的做法是向管理员确认这个虚拟模型可能用到的全部模型，一次加齐。403 不会触发切换到候选模型。

### 主模型失败时会自动换模型吗？ {#routing-fallback}

管理员为规则配置了候选模型时会。按默认策略，模型无可用供应商、429 限流、500 / 502 / 503 / 529 或连接失败时切换；504 / 524 超时、未定价、无权限、额度不足、敏感词拦截不会切换，部分无法判断原因的上游内部错误也不切换。管理员可以调整切换策略。流式请求只在开始输出之前切换。详见[失败时自动切换](/guide/intelligent-routing#失败时自动切换)。发生切换时响应头 `og-route` 为 `FALLBACK`，`og-route-attempts` 大于 1。

## 语义缓存 {#cache}

以下解答接入时的常见疑问，更多操作细节见[语义缓存专题常见问题](/guide/semantic-cache#常见问题)。

### 语义缓存与模型供应商的提示词缓存一样吗？一定能省钱、加速吗？ {#cache-benefits}

不一样。语义缓存命中后直接复用历史回答，不再请求业务模型生成；供应商提示词缓存通常仍会执行模型生成，只是复用部分输入处理结果。

语义查找可能需要 Embedding 调用，未命中后还需继续请求业务模型。因此实际收益取决于命中率、有效期和查找开销。适合答案稳定的常见问答，实时信息、个人状态和需要不同创作结果的任务应谨慎启用。见[语义缓存](/guide/semantic-cache)。

### 相同或相似的问题，为什么没有命中缓存？ {#cache-misses}

缓存匹配还受到 API 凭据、缓存键、接口、流式模式、模型和生成参数等影响；相似问题还需达到语义阈值。首次成功回答在后台写入，立即重试可能仍未命中；条目过期、超出消息条数阈值或未写入也会影响结果。

先看 `og-cache` 响应头：`HIT` 表示命中，`MISS` 表示参与查找但未命中；没有该头时，应检查是否满足缓存前提以及代理是否保留响应头。阈值 `0.8` 表示匹配门槛，**不代表答案有 80% 的正确率**。详见[缓存排障](/guide/semantic-cache#按现象排查)。

### 如何强制重新生成回答？知识更新后旧缓存会自动失效吗？ {#fresh-answers}

使用一个未使用过的 `hcd-og-cache-key`，或由管理员清理相关缓存。知识更新时可将业务键从 `product-faq:v1` 切换到 `product-faq:v2`。

`hcd-og-no-store: true` 只禁止保存本次回答，仍允许读取旧缓存；需要重新生成且不保存时，可同时使用新缓存键与 No-Store。修改默认 TTL 不会让旧条目立即过期，命中也不会续期。操作见[生命周期与清理](/guide/semantic-cache#生命周期与清理)。

### 不同用户会共享缓存吗？ {#cache-isolation}

不同 API 凭据或缓存键不共享条目。如果多个用户共用同一 API 凭据和缓存键，就可能复用回答；需要隔离时，应由可信应用设置不同业务键。

调用方可设置的租户头只是业务标识，不能代替授权。具体匹配条件见[缓存空间与匹配边界](/guide/semantic-cache#缓存空间与匹配边界)。

### 流式和 Responses 请求可以缓存吗？命中后的 `usage` 是本次消耗吗？ {#streaming-cache}

语义缓存支持 Chat Completions、Anthropic Messages 和无状态 Responses 请求，包含流式调用。Responses 使用 `background: true`、`conversation` 或非空 `previous_response_id` 时跳过缓存；`/v1/responses/compact` 不参与缓存。

流式与非流式分别缓存，中断的部分回答不保存。**缓存回放中的 `usage` 是历史响应数据**，不代表本次上游消耗，也不能据此确定本次实际扣费；命中缓存不等于本次总费用为零。支持范围与统计口径见[语义缓存](/guide/semantic-cache)。

## 安全护栏 {#guardrails}

### 安全护栏检查什么？能识别图片、音频或文件里的敏感内容吗？ {#guardrail-coverage}

护栏按管理员配置检查请求与响应中的文本，可用于敏感信息脱敏、提示词注入检测和内容审核。多模态消息中的文本块可以检查，图片、音频和文件块本身会跳过；需要检查其中内容时，需先由业务侧提取文本。

推理过程和部分工具参数也存在覆盖限制，不能把启用护栏理解为检查了请求中的所有内容。具体接口和字段边界见[安全护栏](/guide/guardrails#已知边界)。

### 请求被护栏拦截，还会消耗模型用量吗？ {#blocked-usage}

请求侧拦截发生在转发业务模型之前，不产生这次业务模型生成调用的 Token 消耗。响应侧拦截则需要区分回答来源：

- **本次调用上游生成的回答**：模型已经生成全部或部分内容，相应用量以上游实际记录为准，不会因拦截自动回退。
- **本次命中语义缓存的回答**：回放仍会经过输出护栏，但没有本次业务模型生成调用；历史响应中的 `usage` 不能算作本次生成用量，也不能据此判断总费用为零。

若护栏调用了独立安全审核模型，审核本身也可能产生模型用量，与业务模型调用分别计算。详见[护栏常见问题](/guide/guardrails#常见问题)。

### 如何区分护栏拦截与普通调用失败？为什么流式回答只返回了一部分？ {#guardrail-errors}

护栏拦截的错误类型或错误码为 `guardrail_blocked`。非流式拦截默认返回 HTTP 400，管理员可配置该状态码，应结合错误体和 `og-guardrail` 响应头判断；流式响应开始后若输出被拦截，会发送错误帧并终止，已经下发的内容无法撤回。

**流式响应头只反映请求侧结论**，应结合 SSE 错误事件和服务端日志判断输出侧结果。没有护栏拦截证据时，还需排查网络或上游中断。参阅[拦截时调用方看到什么](/guide/guardrails#拦截时调用方看到什么)。

### 审核服务故障会阻断业务吗？可以先观察再启用拦截吗？ {#moderation-failures}

检查执行失败默认放行，并记录执行错误。若要求审核失败时阻断请求，需要将检查项设为 `fail_on_error: true`，同时让所属护栏启用 `deny: true`，并确保执行失败对应的严重度达到拦截阈值。**仅把执行失败记为违规，不等于一定拦截。** 插件自身异常由独立的 `error_policy` 控制，不能用它代替检查项设置。放行不等于检查通过，管理员应关注 `outcome=error` 事件。

可以先用 `deny: false` 观察命中情况，再启用拦截。注意：观察模式只关闭拦截，**不会关闭脱敏改写**。相关设置见[灰度上线](/guide/guardrails#灰度上线)和[与其他能力的关系](/guide/guardrails#与其他能力的关系)。

### 命中语义缓存的回答会绕过护栏吗？ {#cached-answer-checks}

按规定配置插件顺序后，请求先经过护栏再查缓存，回答先经过输出护栏再写入缓存；命中缓存的回答也会经过当前请求适用的输出护栏。

护栏不会主动扫描并清理存储中的历史条目，需要移除旧内容时应另行清理缓存或切换缓存键版本。配置关系见[与其他能力的关系](/guide/guardrails#与其他能力的关系)。

## 日志与排障 {#troubleshooting}

### 刚调用完为什么查不到日志？看板数据为什么与当前消费不同？ {#delayed-logs}

对于转发到模型服务的调用，额度在调用时实时校验与扣减，控制台中的调用日志、用量和运行字段通过后台任务回流，因此存在延迟。这类调用记录通常约两分钟后出现在日志中，汇总统计也不一定同时更新。

**缓存命中和请求侧护栏拦截不一定产生上游模型调用记录**，不能只等待上述日志同步。应结合 Request ID 查看 Token Gate 的请求日志、缓存监控或护栏事件；这些插件日志与统计需要启用日志插件及对应存储，具体查询入口取决于当前环境的控制台集成。未启用相关记录时，等待或刷新不会补出对应的历史事件。

查不到日志时，先确认时间范围和用户筛选；日志默认显示最近 7 天，主列表保留最近 30 天，更早记录可通过 **历史数据** 查看。持续缺失时，请管理员检查同步状态。见[日志](/user/usage)。

### 成员能查看其他人的调用记录吗？管理员如何追踪配置修改？ {#data-access}

普通成员只能查看自己的调用记录和个人统计，管理员按授权范围查看组织数据，并可按部门、成员、模型等分析费用与用量。

日志追踪模型调用；操作审计追踪管理变更，例如谁修改了 API Key、供应商、定价或路由策略。两者用途不同。成员可查看[个人看板](/user/my-dashboard)，管理员可查看[看板与统计](/user/dashboard)。

### 返回 429 或提示限流，是平台还是供应商在限制？ {#rate-limits}

两者都有可能。启用平台限流规则时，请求可能受租户、API Key 或全局请求频率限制；上游供应商也可能限制其账号或模型的请求量。仅凭 HTTP 429 无法确定限制来自哪一层。

保留错误体、响应头、发生时间和 Request ID，请管理员结合 Token Gate 请求日志、限流规则和上游返回信息定位。平台规则由有权限的管理员核对；上游限制则需检查对应供应商账号的限额和状态。

应用应降低请求频率和并发，采用有间隔的退避重试；如果响应包含 `Retry-After`，按其提示等待。增加重试次数或配置备用供应商都不能保证绕过当前限制。

### 调用失败时，应按什么顺序排查？ {#troubleshooting-order}

先保留完整错误信息，再按现象检查，避免仅凭 HTTP 状态码判断原因。

| 现象 | 优先检查 |
| --- | --- |
| 无法连接、路径不存在 | API 地址、客户端自动补全的路径、网络可达性 |
| 密钥无效或已过期 | 密钥是否完整、是否被关闭或删除、有效期、所属账号状态 |
| 模型不存在或无权限 | 模型 ID、密钥的分组定价与模型限制、供应商承载和启用状态 |
| 额度不足 | API Key 配额、成员额度、账户余额，以及配置同步结果 |
| 只有部分机器失败 | IP 限制、实际出口地址和网络路径 |
| 429 或提示限流 | [限流来源](#rate-limits)、平台规则、上游限额和重试间隔 |
| 超时或上游错误 | 响应错误信息、实际供应商、供应商状态和重试策略 |
| `guardrail_blocked` | 护栏标识、命中事件、请求侧或响应侧拦截 |
| 保存配置后仍无变化 | 同步或热更新结果，再用新请求验证 |

可以使用[快速开始](/guide/getting-started)中的最小请求验证地址、密钥和模型，再逐步恢复应用的其他参数。管理员接入排查见[验证与排障](/admin/providers-and-models#验证与排障)。

### 向管理员反馈问题，需要提供哪些信息？ {#reporting-issues}

提供发生时间及其时区、Request ID（如有）、模型 ID、API Key 名称、接口路径、是否流式、HTTP 状态码和错误内容，并说明影响范围及是否可以稳定复现。缓存问题可附 `og-cache` 等响应头，护栏问题可附护栏标识和流式错误事件。

需要请求样例时先脱敏，不要提供完整 API Key、上游密钥或无关的敏感业务内容。管理员可按这些信息关联调用日志、插件事件和配置变更记录。