常见问题（FAQ）

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

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

产品与部署

OneGateway 解决什么问题？

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

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

已经有模型供应商账号，为什么还需要 OneGateway？

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

支持哪些部署方式？业务数据会发到哪里？

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

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

控制台和网关分别负责什么？应用应该访问哪个地址？

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

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

接入与模型

接入应用需要准备什么？已有应用要改多少代码？

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

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

API 地址要不要加 /v1？模型名称该填哪个？

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

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

如果管理员配置了模型名称映射，日志中的上游实际模型可能与请求的模型 ID 不同。名称不同本身不代表调用出错，可请管理员核对该供应商的映射配置。

可以接入企业自建模型吗？所有模型都支持同样的功能吗？

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

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

为什么同事能看到或调用某个模型，我却不能？

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

在页面看到模型，不代表每一把 API Key 都能调用它；密钥上的限制可以进一步收窄范围。授权关系见分组定价与 API Key。

模型状态是灰色，或价格显示 --，是什么意思？

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

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

API Keys 与权限

OneGateway API Key 和上游供应商密钥有什么区别？

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

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

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

API Key 显示“无限额度”“全部模型”，是否真的没有限制？

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

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

角色、部门、分组定价分别控制什么？

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

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

API Key 泄漏或人员离职时，怎么停止调用？

密钥疑似泄漏时：

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

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

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

为什么同一把 API Key 在部分机器上能用，在其他机器上不能用？

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

额度与计费

成员额度、账户余额和 API Key 配额有什么区别？

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

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

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

新账号第一次调用就提示额度不足，怎么办？

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

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

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

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

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

额度什么时候重置？没用完的能结转吗？

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

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

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

调高额度，会保留本周期已经使用的金额吗？

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

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

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

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

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

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

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

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

费用如何计算？为什么同一模型的费用不完全一样？

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

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

日志的花费显示“订阅”，是不是免费调用？

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

供应商与路由

供应商测试连接成功，为什么模型还是调用失败？

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

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

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

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

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

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

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

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

只创建模型定义就能调用吗？停用模型会影响什么？

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

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

智能路由

以下解答接入时的常见疑问，更多细节见智能路由专题常见问题。

og-auto 是什么？为什么在可用模型里找不到？

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

怎么知道这次请求实际用了哪个模型？按哪个模型计费？

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

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

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

主模型失败时会自动换模型吗？

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

语义缓存

以下解答接入时的常见疑问，更多操作细节见语义缓存专题常见问题。

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

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

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

相同或相似的问题，为什么没有命中缓存？

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

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

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

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

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

不同用户会共享缓存吗？

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

调用方可设置的租户头只是业务标识，不能代替授权。具体匹配条件见缓存空间与匹配边界。

流式和 Responses 请求可以缓存吗？命中后的 usage 是本次消耗吗？

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

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

安全护栏

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

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

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

请求被护栏拦截，还会消耗模型用量吗？

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

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

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

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

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

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

审核服务故障会阻断业务吗？可以先观察再启用拦截吗？

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

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

命中语义缓存的回答会绕过护栏吗？

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

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

日志与排障

刚调用完为什么查不到日志？看板数据为什么与当前消费不同？

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

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

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

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

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

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

返回 429 或提示限流，是平台还是供应商在限制？

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

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

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

调用失败时，应按什么顺序排查？

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

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

可以使用快速开始中的最小请求验证地址、密钥和模型，再逐步恢复应用的其他参数。管理员接入排查见验证与排障。

向管理员反馈问题，需要提供哪些信息？

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

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