网关如何串起一轮提示：x-claude-code-prompt-id 怎么开
走公司 LLM 网关、代理或自建转发时，日志里常见一堆「碎请求」：工具调用、续写、重试各打一条，很难还原「用户这一句提示」对应哪一批上游调用。CLI 2.1.283 增加可选头 x-claude-code-prompt-id，让网关能把服务同一用户提示的请求归到一组。
需要先 opt-in：环境变量 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1。默认不开，避免无谓改请求面。
网关侧 advisor 标签 400、历史 web search 解密失败是另一类故障，见 ANTHROPIC_BASE_URL advisor 400 与 网搜历史 400。本文只讲 prompt-id 关联头。
它解决什么
一轮用户输入在 Claude Code 里往往对应多次模型 HTTP 请求（工具循环、压缩、续写等）。对网关运维来说：
- 没有公共键：只能按时间窗瞎猜「哪些请求是一拨」。
- 有了
x-claude-code-prompt-id：同一用户提示下的请求可带同一关联 id，便于聚合、计费拆分、超时排查。
changelog 原文意图：LLM 网关可以 group / correlate 服务同一 user prompt 的请求。
怎么打开
- 升级到 Claude Code 2.1.283+。
- 在运行环境设置：
bash
export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1- 经你的网关再跑一轮带工具调用的会话。
- 在网关访问日志 / tracing 里确认出现
x-claude-code-prompt-id（具体是否打印、如何建索引取决于网关实现）。
未设置该变量时，不要假定头一定存在——这是显式可选能力。
谁该开
适合：
- 自建或公司统一 LLM Gateway / 反向代理，要做按「用户提示」聚合的指标。
- 排障「这一轮为什么打了 20 次上游」。
- 需要把网关侧限流、配额按「对话回合」而不是「裸 HTTP」理解。
可以先不开：
- 直连官方 API、没有中间层要读这个头。
- 网关尚未支持自定义头入库——开了也看不到收益。
和可观测、压测的边界
同版本还有相关周边（按需取用，别和 prompt-id 混成一个开关）：
| 能力 | 用途一句话 |
|---|---|
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 | 给网关提示头（含 prompt-id） |
OTEL_LOG_TOOL_CONTENT=1 | 把 MCP / WebFetch / WebSearch 等输出记到 tool.output span 事件 |
apps gateway load_test_mode | 构建并签名请求但不发上游，回罐头响应，便于安全压测 |
个人本机开 OTEL 内容日志前，先想清楚工具输出是否含密钥；网关 hint 头则主要影响中间层可观测性。
实践建议
- 网关先改、客户端后开：确认代理会转发并保留未知头，再设环境变量。
- 和现有 trace id 并存：prompt-id 解决「同一用户提示」维度；请求级 trace 仍可保留。
- 出 400 时别只怪这个头：advisor / 历史解密等问题要走对应修复与升级路径。
- 文档给运维：写明「看哪个字段聚合一轮提示」，减少对终端用户的误伤排查。
中间层越厚，越需要「这一轮提示」的共同钥匙。x-claude-code-prompt-id 很小，却是网关侧把碎请求重新串成故事的关键一步。