30. 网关请求、会话与根因定位

完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向平台管理员、运维人员与安全审计人员，说明如何检索单次网关请求、读懂请求详情的五个页签、区分失败类型、识别调用来自哪个客户端；如何按会话还原多轮对话，查看员工与智能体会话的特有信息，并在链路详情中评论、评分、送审；如何查看智能体的运行状态与生命周期事件、MCP 工具调用活动与策略命中；最后给出常见现象的根因定位顺序。入口与可见角色见第 29.1 节；按现象排查的完整路径见第 31 章。

30.1 检索网关请求

「请求」页签记录经过网关的每一次模型、MCP、A2A 与 API 服务调用，包括被策略拦截的请求。员工在「对话」中使用智能体时，智能体发出的模型调用同样记录在这里。排查任何运行期问题，都从这里找到目标请求开始。

前提：账号为租户管理员，或具备运营、财务、审计等职责角色。运营角色只看到本人发起的请求。

操作步骤

1. 进入「管理后台 › 观测中心 › 运行总览」，选择「请求」页签，在工具栏选择覆盖问题发生时间的时间范围。页面上方的「请求趋势」条可拖选，进一步缩小时间窗。
2. 已知请求 ID、链路 ID 或成员时直接在搜索框输入。请求 ID 取自响应头 x-request-id（或 x-lp-data-plane-request-id），链路 ID 取自 x-trace-id。
3. 需要按条件筛选时点「筛选」添加条件。条件以「字段 = 值」显示在工具栏，点「×」移除，点「清空」全部移除。
4. 点击目标行打开请求详情（30.2 节）。详情左上角可用上一条、下一条在当前列表中切换。
5. 常用筛选组合可通过「视图」保存；需要导出当前结果时点「导出 CSV」。

常用条件包括：结果（已完成 / 失败 / 已取消 / 已拦截）、HTTP 状态码、耗时区间、发起人、接入凭据、客户端、终端用户、模型、供应商、渠道、调用类型、MCP 工具、命中策略、责任方、该次尝试失败、网关兜住方式（重试、故障转移、排队）、用途、推理强度、标签、会话 ID、请求 ID。列表主要列包括链路 ID、发起人 · 客户端、部门、上游端点、全周期耗时、结果、失败阶段、时间、请求造型、耗时构成、网关耗时、上游响应耗时、模型、用途、推理强度、用量与费用。

注意

• 「导出 CSV」为固定字段，导出的是当前筛选结果。列表规模很大时，优先缩小时间范围或用请求 ID 精确搜索。
• 因密钥写错、伪造而认证失败的请求无法确定调用身份，按接入凭据或发起人筛选时不会出现；排查时用调用方收到的 x-request-id 按请求 ID 搜索。

30.2 阅读请求详情

详情页头显示链路 ID、结果、发起人与请求造型，右上角提供「看该模型流水」「看该会话」（属于会话的请求显示）与刷新。五个页签分别回答：

「概要」分四组：身份归属（链路 ID、请求 ID、网关事件 ID、所属空间、发生时间、保留期）、发起人与凭据（发起方类型、发起人、发起人邮箱、客户端识别、接入凭据前缀、客户端 IP、入口 IP 异常）、调用对象与模型解析（事件类型、请求造型、对象类型、客户端声明的模型、实际路由模型、计量分组）、标签。

四段报文与差异

1. 在报文区选择段落：「客户端请求」「发往上游的请求」「上游响应」「返回客户端的响应」，每段标出字节数。发生重试或故障转移时，上游各段按尝试次序分开。
2. 在每段下切换「正文」「请求头」（或「响应头」）；「复制全文」复制当前段。
3. 在「发往上游的请求」下选择「差异」，查看网关相对客户端请求做了哪些改动。跨协议转发时页面顶部注明入站与上游协议，例如「跨族转发：入站 Anthropic Messages → 上游 OpenAI Chat Completions」；未能转发到上游的字段在「未转发到上游」中逐项列出。

时延与路由：「时延与成败」给出状态、HTTP 状态码、失败阶段、错误类别与拦截原因，并以甘特条展示耗时分解（分段含义见第 29.2 节），被拦截的请求各耗时字段为空。「路由与改写」的「请求去向」给出声明的模型、接管规则、最终供应商与模型及路由结论；「上游尝试」逐行给出序号、档位、供应商 / 模型、账号与选号理由、结果、原因、状态码、耗时、首字时间与参数调整；「请求改动」列出按目标能力调整的内容与规则改写；「命中记录」给出本次命中的全部策略及其处置与故障转移。

注意

• 请求头中的 authorization 等凭据在采集时抹除；每次读取正文或差异都写入审计记录。
• 报文不可读时页面给出原因，例如按数据留存设置未留存报文、报文已超过留存时长并已清理、报文归档中稍后可查看（第 29.5 节）。
• 被策略拦截的请求没有上游段，差异视图只在请求方向提供。
• 「请求去向」区域可能提示「本次请求未保存规则链快照」，此时以「命中记录」为准；规则已被删除时会标注并保留历史命中。

30.3 区分失败类型

同样是「调用失败」，原因可能在上游、在策略、在额度，也可能在调用方自身。按以下线索区分：

查看故障转移与切换代价：在「筛选」中添加「网关兜住方式 = 故障转移」列出相关请求；打开一条，在「上游尝试」中逐行查看每次尝试的档位、结果与耗时。两次耗时之和即用户感受到的总时间，第一次尝试的耗时就是切换代价。代价过大时调整对应流量规则中该档位的超时时间（第 26 章）。

30.4 识别调用来自哪个客户端

网关按请求头 User-Agent 等特征自动识别常见的智能体客户端，例如 Claude Code、Codex、WorkBuddy；无法识别的显示为「自定义客户端」或「未知客户端」。识别结果显示在「请求」列表的「发起人 · 客户端」列、请求详情「概要 › 客户端识别」、会话列表与详情，以及 MCP 服务的「调用来源」列（30.8 节）。

注意

• 调用方自研程序没有可识别特征时，可在「获取 API 密钥」时为其新建并命名客户端，请求会归入该客户端（第 20 章）。
• 客户端识别用于统计与排查，不作为访问控制依据；按客户端限制访问应使用流量规则的条件（第 26 章）。
• 模型调用的客户端识别与 MCP 调用的来源识别是两套判断。判断实际来源时两处都看。

30.5 查看会话与对话记录

多轮调用按会话串联：调用方在请求头携带 x-zenova-conversation-id: <会话标识> 时，同一标识的调用归入同一会话；未携带时网关按对话内容的延续关系自动归并；客户端通过 OTLP 上报的步骤并入对应会话（第 29.3 节）。员工在「对话」中与智能体的会话同样出现在这里。

操作步骤

1. 在「运行总览」选择「会话」页签。列表列出标题（取首条用户消息）、客户端、接入、成员、来源、轮次、费用、最近活动；「来源」取值为网关、客户端上报、网关与客户端上报。可按客户端、来源、诊断问题类别（执行异常、用量问题、质量问题、安全问题）筛选。也可在请求详情点「看该会话」直接进入。
2. 打开会话详情。页头显示最终用户、组织、调用方、密钥与活跃时段，以及「进行中」或「空闲」状态；「会话信息」下拉列出终端用户、所属组织、接入智能体、网关凭据、安全策略、最后活跃与最新消息。右上角提供「导出 JSONL」「导出报告 PDF」。
3. 切换到「对话」页签：左侧按轮列出首句、费用与耗时，可按「全部 / 失败 / 网关兜住 / 无网关记录」过滤、按时间或耗时排序并搜索对话内容；右侧显示所选轮的用户输入、模型回复，以及该轮耗时、模型调用次数、重试、工具调用和每次模型调用的模型、Token、耗时与结果。

其余页签

导出会话：「导出 JSONL」提供「Hermes 训练格式」（整段会话一行）与「轮次运维明细」（每轮一行，含耗时、重试与 Token）两种格式。「导出报告 PDF」生成含会话概览、Token 与成功率、每轮摘要、网关调用结论、故障明细、策略命中、诊断与审计事件的报告，可用于离线归档。

注意

• 调用方以同一个 x-request-id 重发请求时，两次调用都会保留；平台把重发归入「客户端重发的上下文」，不计入「重试」计数。轮次的「重试」统计的是网关内部发起的重试。
• 用户在客户端回退、编辑后重发或重新生成时，原来那一轮被新的一轮替换，标为「已替换」并默认隐藏；打开「显示回退 / 重发前的旧轮」后不编号地显示。客户端首次接入时带来的历史对话标为「历史」，没有花费和耗时。
• 「网关调用」页签显示「本会话未经平台网关调用模型」时，客户端可能直连了上游，这部分的成本、失败与策略在网关侧都看不到。
• 会话列表数据量大时没有关键字搜索框。按标题定位具体会话时，从请求详情的「看该会话」进入更快。
• 导出入口按会话来源显示，客户端上报型会话可能只提供「导出报告 PDF」。

30.6 智能体会话与链路详情

适用场景：员工反馈某个智能体回答异常、反复调用工具或定时任务结果不对，需要还原智能体的执行过程。

识别智能体会话

• 会话详情页头的「调用方」显示智能体名称与头像，「会话信息」中的「接入智能体」给出所属智能体。
• 由定时任务触发的轮次标「定时任务」，由心跳触发的轮次标「心跳」，这两类轮次的开场消息可能来自智能体本身。
• 某一轮派生了子代理、辅助调用（起标题、生成建议等）或上下文压缩时，轮次旁显示「子代理 N」「辅助 N」「压缩 N」，点击进入对应链路查看。
• 「对话」页签中，智能体内部使用的上下文折叠为「智能体内部上下文（N 条）」，客户端注入的上下文折叠为「客户端注入的上下文（N 条）」。
• 消息区显示「消息内容未上报」并说明「该会话由智能体运行时托管，消息内容未同步到平台」时，表示该会话的消息正文保存在智能体运行环境中，平台只有调用记录；显示「系统内部会话」时为心跳、例行任务等内部会话，不展示用户消息。

在链路详情中下钻

1. 在会话详情的「客户端轨迹」中选中一条记录（列表与「联动图谱」均可），在右侧记录详情的标题下点「在链路中查看」进入链路详情；来自日志的记录没有对应链路，该位置会给出说明。成员在工作台「洞察 › 会话」中打开本人会话后同样可以进入。
2. 用左侧「时间线」「回放」「图」视图定位耗时最长或失败的步骤；在「时间线」与「图」中可用搜索框按模型、工具或关键词查找步骤，命中的步骤会自动展开并滚动到可视区域。
3. 选中步骤后在右侧「输入输出」中查看该步骤实际收到与返回的内容，可在 Markdown、JSON、原文之间切换；工具步骤分「入参」「返回」显示，治理步骤记录的是一次决策，不产生模型输入输出。
4. 展开页头下方的提示条，查看「耗时异常的步骤」与「高频重复调用」。这些提示是线索，不是结论；重复调用可能来自合法重试或并行分片，需结合父子关系与工具返回判断。

记录结论与后续处理

页头提供「操作」菜单：

注意

• 链路详情中的输入输出同样受数据留存设置约束；页面提示「读不到原文」与「观测事件按规约不保存提示词和回复」是两种情况，前者应上报，后者表示该调用本身没有可关联的会话正文。
• 模型调用已结束但输出 Token 为 0 时，页面顶部提示这是空输出或截断，不是一次成功的回答。

30.7 智能体运行状态与生命周期事件

适用场景：员工反馈智能体无响应、对话报「智能体运行环境暂不可用」，或需要确认运行时版本升级的进度。

操作步骤

1. 进入「管理后台 › 智能体 › 智能体运营」。页面顶部统计总数、运行中、异常与运行时落后的智能体数量；列表列出智能体、工作区、状态（运行中 / 已停止 / 异常）、服务状态、运行时、节点、升级状态与创建时间。可按名称搜索，按工作区与版本筛选。
2. 平台正在分批升级智能体运行时版本时，页面显示「运行时版本升级进行中」卡片，给出进度、目标版本与待升级、升级中、待健康检查、已完成、已跳过各组数量。可调节「同时升级上限」；连续失败过多时升级「已自动暂停」，排查后点「恢复升级」。
3. 点击某个智能体打开「智能体详情」，在「概览」「身份」「运行时」「最近错误」中查看所有者、模型、副本、运行镜像、重启次数、最近重启、停止原因、最近错误与错误时间；「事件」区块列出生命周期事件。
4. 需要处置时，在行操作中选择「启动」「停止」「重启」「重新下发配置」或「查看生命周期事件」。停止前会弹出确认，停止后该智能体不再提供服务。
5. 需要查看单个智能体的业务执行时，在工作台打开该智能体：「运行历史」列出活动日志（时间、来源、状态、消息，可展开事件详情与容器日志）；「定时任务」中每个任务的「执行历史」列出来自运行时的最近 50 次执行；「操作审计」与「用量统计」分别给出配置变更与用量（第 14、15 章）。

你会看到

• 「最近错误」以中文说明失败类型，例如生命周期操作超时、模型分组分发解析失败、配置下发冲突、状态转换超时。
• 运行时标为「运行时落后」时，表示该智能体尚未升级到当前运行时版本。

注意

• 「智能体运营」需要运营域管理权限。启停与重启会影响正在使用该智能体的员工，处置前先确认影响范围。
• 定时任务的执行历史需要从运行中的智能体获取；智能体未运行时提示先启动智能体。

30.8 查看 MCP 工具调用活动

MCP 服务的每次工具调用、配置导出、令牌签发与撤销都会留下活动记录，可用于确认谁在什么时候用哪个客户端调用了哪个工具。智能体通过平台调用 MCP 工具时，同样记录在这里。

操作步骤

1. 进入「管理后台 › 能力 › MCP 服务」，打开目标服务，选择「调用情况」页签。
2. 页面顶部显示服务状态、限流与熔断状态；「调用趋势」可在「业务调用」「协议活动」「全部活动」之间切换并选择时间范围，下方显示调用量、成功率、平均耗时、P95 耗时与当前并发。
3. 在「最近调用」中查看每次调用，可用右上角「全部调用方」按用户筛选。
4. 点击一行查看「调用载荷」：客户端请求、发往上游的请求、上游响应、返回客户端的响应四段正文与请求头。

「最近调用」列出时间、调用来源（客户端名称与来源入口）、用户、工具、类型（工具的副作用类型）、状态与结果（失败时给出原因，例如「上游服务错误」「参数无效」）、耗时与来源 IP。需要跨服务查看时，在「运行总览 › 请求」中添加「调用类型 = MCP 调用」或「MCP 工具」筛选，可使用与模型调用相同的请求详情。

控制面事件与审计

• 成员在工作台导出 MCP 连接配置、签发令牌、撤销令牌，都会记入该服务的活动记录（「全部活动」）。
• 令牌签发与撤销同时写入「管理后台 › 审计与合规 › 操作审计」，记录操作人、对象、时间与来源 IP。
• 连接配置中的令牌只显示一次并带到期时间；活动记录与审计中只显示令牌指纹前缀。

30.9 规则命中与流量突增

规则命中：「规则命中」页签按规则汇总策略在时间窗内的命中情况。

1. 在「运行总览」选择「规则命中」页签，选择时间范围（默认最近 7 天）。
2. 列表按规则列出策略规则、匹配判定条件、网关执行动作、命中次数与来源数、下钻查看、最近命中、7 天走势；搜索框可按规则名称或 ID 搜索。
3. 点「筛选 › 处置」，按放行、拒绝、改路由、改写、降级、限速筛选。
4. 点某条规则的「下钻命中请求 ➔」，页面切换到「请求」页签并自动带上「命中策略」筛选，打开其中一条即可在「路由与改写 › 命中记录」中核对处置与结果。

注意：列表是按规则的汇总，逐条记录在下钻后的请求列表或请求详情中查看；对护栏类规则下钻后结果为空时，改用「请求」页签按「命中策略」直接筛选该规则。

流量突增与熔断事件

适用场景：出现流量异常、上游熔断或费用突增时，需要确认发生了什么、影响多大。

1. 在「运行总览 › 总览」查看「流量潮汐与双向承压」，对比当前 QPS 与上游生成、预填充 Token 的走势，判断是请求变多还是单请求变长。
2. 用筛选收窄到可疑的接入凭据或模型，观察其请求量与失败率（第 28 章）。
3. 进入「管理后台 › 运行与排障 › 告警规则」，点「新增规则」，在「指标」中选择要盯的信号：调用量看「模型调用量」，限流看「MCP 限流次数」「限流排队超时率」，成本看「单次调用成本均值」，延迟看「模型调用 P95 延迟」「网关耗时 P95（排队＋处理）」，策略事件看「策略命中」「策略拦截占比」「策略执行出错」「故障转移占比」（第 32.4 节）。
4. 判断突增或突降时，「取值方式」选「相对基准的变化比例」，并填写「基准窗口」（不短于统计窗口）。比值是统计窗口读数除以基准窗口读数：「大于 3」表示涨到基准的 3 倍以上，「小于 0.3」表示降到基准的 30% 以下。
5. 在「运行总览」选择「告警」页签，查看告警记录、最近取值与状态变化。

注意：基准窗口读数很小时比值容易失真，例如空闲时段每小时一两次调用降到 0，可填「基准下限」排除这类时段。告警规则只作用于本租户；没有选择通知渠道的规则发往本租户订阅了「告警」且已确认收到测试消息的渠道，没有这样的渠道时只在平台内记录（第 32 章）。

30.10 根因定位顺序

能力说明

---

上一章：29. 可观测入口、数据来源与权限边界 · 下一章：31. 问题诊断与处理