# v0.2 Codex API Forwarder 稳定外部通道规格

`hwlab-codex-api-forwarder` 是 `hwlab-cloud-api` Pod 内的本地 sidecar，监听 `127.0.0.1:49280/responses`，为 Code Agent `codex-api` provider profile 提供到 hyueapi Responses upstream 的直连 HTTP 转发通道。它没有独立 Kubernetes Service，但属于 v02 稳定外部 provider 通道的一部分。

## 在系统中的职责划分

- 为 `hwlab-cloud-api` 中的 `codex-api` profile 提供 OpenAI Responses 兼容上游，不经过 `hwlab-deepseek-proxy`。
- 保证 `hyueapi.com` / `.hyueapi.com` 保留在 `NO_PROXY` / `no_proxy` 中，避免被 G14 proxy 或其他 egress 配置劫持。
- 只在同 Pod loopback 暴露，不向 ClusterIP、公网、浏览器或普通用户开放。
- 使用同一个 Code Agent provider SecretRef 注入鉴权材料，但自身不记录或打印 Secret 值。

## 内部架构

- `cmd/hwlab-codex-api-responses-forwarder/main.ts` 启动 HTTP proxy。
- listen host 默认 `127.0.0.1`，端口默认 `49280`。
- upstream 默认 `https://hyueapi.com`，可由 `HWLAB_CODE_AGENT_CODEX_API_UPSTREAM_BASE_URL` 覆盖。
- forwarder 会过滤 hop-by-hop headers、限制请求体大小，并按 upstream base path 规范化 `/v1/responses`、`/v1/models` 等路径。

## API 接口说明

| 接口 | 说明 |
| --- | --- |
| `GET /health`、`GET /health/live`、`GET /health/liveliness` | 本地 forwarder 存活检查，返回 upstream host 和 required NO_PROXY entries。 |
| `GET /health/readiness` | 本地 readiness，不证明 upstream provider 鉴权可用。 |
| `POST /v1/responses` | Codex API profile 的 Responses 请求代理入口。 |
| `GET /v1/models` | 按 upstream base path 代理模型列表请求。 |

## 测试规格

## T1

阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：在 `hwlab-cloud-api` Pod 内访问 `127.0.0.1:49280/health/live`，确认 `upstream.host` 为 hyueapi 域名，且 `NO_PROXY` / `no_proxy` 包含 `hyueapi.com` 和 `.hyueapi.com`。

## T2

阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/agent/chat` 指定 `codex-api` provider profile 做短连接聊天，只有 result completed 且 assistant reply 非空才算 provider 通道通过。

## T3

阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：确认该 forwarder 没有独立 Kubernetes Service，也没有公网端口；所有调用都应来自同 Pod `hwlab-cloud-api`。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| loopback Responses forwarder | 已实现 | `hwlab-cloud-api` Pod sidecar 监听 `127.0.0.1:49280`。 |
| hyueapi direct NO_PROXY | 已实现/持续约束 | forwarder 启动时合并 required NO_PROXY entries。 |
| health/readiness | 已实现 | health 返回 upstream 和 no_proxy 信息。 |
| provider auth 真实验收 | 已实现/持续约束 | 必须通过 `/v1/agent/chat` 短连接 result 判定。 |
| 独立 Service/公网暴露 | 不采用 | 只能由同 Pod loopback 调用。 |

