Codex Search 能力

这是 Responses 下的能力，不是新的 API family

Codex 使用 OpenAI Responses 调用入口时，可能按需触发 Search。8788 为兼容客户端提供一个极薄的传输 operation，但不新增顶级协议、独立模型商品或独立计费系统。

什么时候会调用

通常不需要用户直接调用本页接口。Codex 客户端会在需要检索资料时自动发起 Search，然后继续原始 Responses 会话。Search 请求依赖客户端生成的会话上下文和调用标识；不要脱离会话手工拼接 Search 响应或 function_call_output。

用途	方法与路径	鉴权
Codex Search capability	`POST /v1/alpha/search` 或 `POST /v1/alpha/search/`	`Authorization: Bearer <用户 API Key>`

裸 /alpha/search 不属于公开入口。Base URL 仍填写 https://dingjiai.com/v1，客户端会按自身规则发起请求。

网关读取 model 复用当前 Responses 调用入口的商品和上游候选选择；不维护独立 Search capability 开关。
当前 Codex 请求通常包含 id、model、input、commands.search_query、settings 和 max_output_tokens；查询文本位于 commands.search_query[].q。
请求体按上游合同原样透传，不删除 prompt_cache_* 或未知字段，不把它转换成 Responses 请求。
上游的 status、Content-Type 和 body 由网关透明返回；Alpha 响应不套用普通 Responses usage 解析器。
Search 默认复用 Responses 上游候选；具体参数是否支持由上游决定。上游明确返回 404/405 时，8788 只在 Search operation 内切换候选，不影响普通 Responses。

Search 是 Responses 工作流中的能力调用，不单独创建 usage、预留或 ledger 扣费。随后普通 Responses 请求仍按 Responses usage 结算。上游是否消耗自身资源不改变 8788 的用户计费合同；不能凭空估算 Search token 或新增固定费用。

现象	含义
`404`（裸 `/alpha/search`）	路径不属于公开合同，应使用 `/v1/alpha/search`。
`400 upstream_invalid_request`	上游不接受请求体或缺少会话上下文；先让 Codex 自动管理，不要手工改写成另一种协议。
上游 `404/405` 后继续尝试其他上游	该候选可能没有 Alpha endpoint；这是 Search operation 专属 failover，不代表普通 Responses 不可用。
`502 upstream_not_configured`	当前 Responses 模型没有可用的上游候选。
Search 成功但没有独立扣费	正常；后续 Responses 请求才按既有 Responses usage 结算。

排查时保留响应头 X-Request-Id，并按 request_id 排障查看 operation、attempt 和后续 Responses 结算记录。

管理端“测试上游”验证的是所选 Responses entry/model 的普通探针，不等于 Search 验收。Search 是否可用以真实 Codex 请求和对应 attempt 为准。

这是 Responses 下的能力，不是新的 API family

用途	方法与路径	鉴权
Codex Search capability	`POST /v1/alpha/search` 或 `POST /v1/alpha/search/`	`Authorization: Bearer <用户 API Key>`

裸 /alpha/search 不属于公开入口。Base URL 仍填写 https://dingjiai.com/v1，客户端会按自身规则发起请求。

网关读取 model 复用当前 Responses 调用入口的商品和上游候选选择；不维护独立 Search capability 开关。
当前 Codex 请求通常包含 id、model、input、commands.search_query、settings 和 max_output_tokens；查询文本位于 commands.search_query[].q。
请求体按上游合同原样透传，不删除 prompt_cache_* 或未知字段，不把它转换成 Responses 请求。
上游的 status、Content-Type 和 body 由网关透明返回；Alpha 响应不套用普通 Responses usage 解析器。
Search 默认复用 Responses 上游候选；具体参数是否支持由上游决定。上游明确返回 404/405 时，8788 只在 Search operation 内切换候选，不影响普通 Responses。

现象	含义
`404`（裸 `/alpha/search`）	路径不属于公开合同，应使用 `/v1/alpha/search`。
`400 upstream_invalid_request`	上游不接受请求体或缺少会话上下文；先让 Codex 自动管理，不要手工改写成另一种协议。
上游 `404/405` 后继续尝试其他上游	该候选可能没有 Alpha endpoint；这是 Search operation 专属 failover，不代表普通 Responses 不可用。
`502 upstream_not_configured`	当前 Responses 模型没有可用的上游候选。
Search 成功但没有独立扣费	正常；后续 Responses 请求才按既有 Responses usage 结算。

排查时保留响应头 X-Request-Id，并按 request_id 排障查看 operation、attempt 和后续 Responses 结算记录。

管理端“测试上游”验证的是所选 Responses entry/model 的普通探针，不等于 Search 验收。Search 是否可用以真实 Codex 请求和对应 attempt 为准。