一、为什么接入后还要做请求追踪

只要是团队使用 Codex，就一定会遇到“我刚才这次请求为什么不对”的问题。可能是模型名填错，可能是上下文太长，可能是 Key 权限变化，也可能是提示词里混入了过期需求。如果没有追踪记录，每次排查都只能靠回忆。

请求追踪的目标不是把所有内容都记录下来，而是保留足够判断链路问题的信息。灵能API负责统一 API 中转站入口，CC Switch负责配置切换，追踪日志则负责记录这次调用属于哪个项目、哪类任务、哪张配置卡、结果是否成功。

二、追踪日志不要等出问题才补

很多团队在链路稳定时不记录，等异常出现才发现没有任何依据。请求追踪最好从第一次接入就开始设计，哪怕字段很少，也要保证每次调用都能回到同一套记录口径。

字段不需要复杂，但必须稳定。今天记模型名，明天记项目名，后天只写一句“失败了”，这种记录无法形成排查价值。

• 谁发起：成员、脚本或自动化任务。
• 用什么：CC Switch 配置卡、模型名称、任务类型。
• 做什么：代码生成、审阅、排障、文档整理或测试补齐。
• 结果如何：成功、失败、超时、格式不符或需要人工复查。

三、先确认灵能API入口和基础状态

开始设计追踪流程前，先进入灵能API https://www.lnsns.com/，确认 API *ase、可用模型、账号状态和当前项目使用规则。所有追踪字段都要围绕真实接入信息建立，不能用旧截图或历史配置凑数。

团队文档里可以把灵能API设置成可点击入口，方便成员核对信息。需要注意的是，请求追踪不等于记录完整请求；完整 Key、真实用户数据和内部账号都不应该进入日志。

四、CC Switch 配置卡要参与日志命名

如果团队使用多张 CC Switch 配置卡，日志里必须记录配置卡名称。否则排查时只知道“Codex 输出不对”，却不知道它当时用的是轻量配置、审阅配置还是文档配置。

日志里记录配置卡，比只记录模型名更有用。因为配置**常包含任务意图、输入边界和使用场景，能帮助团队更快判断是否误用了配置。

• codex-dev：日常开发与局部修改。
• codex-review：diff 审阅与风险检查。
• codex-de*ug：错误日志分析和复现步骤整理。
• codex-do**：文档、说明和复盘整理。

五、建议的追踪字段

第一版追踪日志可以用表格或 **ON Lines 保存。重点是字段可读、可筛选、可复盘，而不是一开始就做复杂平台。

{
  "trace_id": "codex-20260903-001",
  "project": "project-a",
  "task_type": "de*ug",
  "config_card": "codex-de*ug",
  "model": "team-selected-model",
  "input_size": "short|medium|large",
  "result": "success|failed|timeout|needs_review",
  "error_category": "none|auth|model|network|for**t|context",
  "created_at": "2026-09-03T10:30:00 08:00"
}

trace_id 很关键。它可以把一次请求、一次截图、一次复现包和一次工单备注串起来。后续有人问“当时那次失败是哪次”，直接用 trace_id 就能定位。

六、日志脱敏要写成规则

请求追踪最容易踩的坑，是为了方便排查而把敏感信息写进日志。正确做法是记录元信息，不记录敏感原文；必要时保存脱敏摘要，而不是完整请求。

灵能API https://www.lnsns.com/ 作为统一入口时，日志只需要记录它对应的配置名称和调用结果，不需要把**敏感页面复制进排查材料。

• Key：不记录完整值，只记录配置来源或变量名。
• 用户信息：手机号、邮箱、订单号、账号 ID 做替换。
• 业务内容：只保留模块、错误类型、影响范围，不保留隐私数据。
• 截图材料：上传前检查是否包含账号、余额、密钥或内部域名。

七、错误分类比原始报错更有价值

很多日志只记录一长串异常文本，读起来费劲，也不利于统计。建议把错误先归类，再保留简短摘要。这样一周后复盘时，能看出主要问题集中在哪一类。

有了分类，***就能更快判断该修接入、修配置、修提示词还是修知识包。不要每次都从原始报错重新读起，那样太耗时间。

• auth：Key 无效、权限不足、账号状态异常。
• model：模型名错误、模型不可用、配置卡未同步。
• network：网络超时、连接失败、**或 DNS 问题。
• for**t：输出格式不符合要求，需要调整提示词。
• context：输入材料不足、上下文过长、资料互相冲突。

八、本地最小复现包怎么准备

当某次 Codex 调用效果异常时，最好不要直接把完整对话转发给别人。更规范的方式是准备一个最小复现包：只保留能复现问题的输入、配置说明和预期输出。

replay-pack/
  README.md              问题说明、trace_id、复现步骤
  input-re**cted.md      脱敏后的输入材料
  expected-output.md     期望输出结构
  actual-output.md       实际输出摘要
  config-note.md         CC Switch 配置卡名称、模型名、任务类型
  check-result.md        人工复查结论

复现包越小，定位越快。它不追求还原全部上下文，而是保留足够证明问题的材料：同样输入、同样配置、同样预期，是否还能得到类似偏差。

九、用 Codex 生成复现包摘要

你也可以让 Codex 帮忙整理复现包摘要，但要先脱敏。输入给它的不是完整账号和真实数据，而是处理后的问题材料。

请根据以下脱敏材料生成问题复现摘要。
必须包含：trace_id、任务类型、使用配置卡、输入摘要、预期输出、实际偏差、需要人工确认的问题。
不要补充不存在的账号信息，不要还原被脱敏的数据。

这类摘要适合写回工单或排查文档。别人接手时，不需要重新读完整对话，只看复现包就能理解问题范围。

十、如何判断是配置问题还是提示词问题

请求失败不一定是接入问题，输出不理想也不一定是模型问题。排查时可以先按顺序判断：链路是否通、配置是否正确、输入是否充分、输出格式是否被明确要求。

这个判断顺序能减少无效排查。先确认链路，再确认配置，最后讨论提示词和模型表现，思路会清楚很多。

• 最小请求失败：优先看 API *ase、Key、模型名和网络。
• 最小请求成功，真实任务失败：看上下文长度、材料冲突和任务范围。
• 内容正确但格式混乱：看提示词是否给了明确输出结构。
• 偶发好坏不一：看样本是否稳定，配置是否被多人临时修改。

十一、每周看一次追踪统计

追踪日志如果只在故障时看，价值会少一半。建议每周***轻量统计，看看哪些错误最常见、哪些配置卡最容易出问题、哪些任务最容易需要人工返工。

周复盘指标：
总请求次数：
失败次数：
超时次数：
格式不符次数：
上下文不足次数：
最常出问题的配置卡：
需要更新的提示词模板：
需要补充的知识包内容：

如果连续几周都出现 context 类错误，说明团队的知识包或工单输入需要加强；如果 for**t 类错误很多，说明提示词模板还不够清楚。追踪的意义，就是把感觉变成证据。

️ 十二、自动化脚本要带 trace_id

如果团队把 Codex 调用放进脚本，例如自动生成摘要、整理日志、辅助审阅，就更应该带 trace_id。自动化任务一旦失败，没有 trace_id 会很难定位是哪一轮输入出了问题。

自动化越多，追踪越重要。灵能API与 CC Switch 解决的是接入和切换，trace_id 解决的是后续谁来排查、怎么排查、根据什么排查。

• 脚本启动时生成 trace_id，并写入本地日志。
• 输出文件名带 trace_id，方便和日志对应。
• 错误摘要带分类，不直接保存敏感原文。
• 复现包只保存脱敏输入和必要配置说明。

十三、完整落地顺序

• 第一步：进入灵能API https://www.lnsns.com/，确认 API *ase、模型范围和账号状态。
• 第二步：在 CC Switch 中按任务类型建立配置卡，并统一命名。
• 第三步：为每次 Codex 调用生成 trace_id，记录项目、配置卡、模型和结果。
• **步：制定日志脱敏规则，不记录完整 Key 和真实用户数据。
• 第五步：把错误分成鉴权、模型、网络、格式、上下文几类。
• 第六步：出现异常时准备最小复现包，而不是转发完整对话。
• 第七步：每周复盘追踪统计，更新提示词模板和知识包。

✅ 十四、结语：能复现的问题，才真正好解决

Codex API 中转站接入完成后，请求追踪会变成团队稳定使用的关键能力。灵能API提供统一入口，CC Switch管理配置卡，trace_id、脱敏日志和复现包则把一次次调用变成可排查记录。

当问题出现时，团队不必靠猜测判断原因，而是能根据配置、输入、结果和错误分类逐步定位。接入链路越常用，越需要这种可观察、可复现、可复盘的工作流。