sub2api codex_cli_only rejects official Codex requests after client identifiers are stripped

Read the custom-provider forwardClientHeaders allowlist and its configuration validation, then trace how Responses and native compact/fallback requests copy client metadata. Add coverage for explicitly forwarding x-codex-window-id and x-codex-installation-id, including provider-header precedence and rejection of arbitrary x-codex-* fields. Done means opted-in identifiers pass through when present, default-off behavior and credential filtering remain intact, and the regression tests pass.

Client or integration

Codex CLI; also observed in Codex App. Captured CLI version: 0.166.0-alpha.6, macOS ARM64.

Provider or upstream service

zzzcoding, a sub2api-backed Responses gateway with codex_cli_only restrictions. The endpoint and credentials in the example below are placeholders.

OpenCodex version

2.97.0. The same four-name forwardClientHeaders allowlist is present on dev at 0a30c551304927c93c26a96c034bd39a166c7460.

Endpoint or capability

POST /v1/responses, openai-responses adapter with authMode: key; preservation of original Codex client metadata.

Current behaviour

The same official Codex CLI can complete a request directly through this gateway, but receives HTTP 403 through OpenCodex. Disabling Responses WebSocket does not fix the HTTP path. The local proxy is reachable and the configured Responses path is correct.

The captured official-client request includes x-codex-window-id but does not include x-codex-app-version. OpenCodex's custom-provider metadata allowlist only accepts originator, x-client-request-id, x-codex-app-version, and user-agent, so enabling all four still drops the actual x-codex-window-id signal. Adding that name to the configuration is rejected by validation.

Expected behaviour

A custom Responses provider should be able to explicitly opt into forwarding the client's original x-codex-window-id and x-codex-installation-id when present, with provider-configured headers retaining precedence. Credential filtering and the default-off policy should remain intact. Missing identifiers must not be generated and arbitrary x-codex-* fields must not be admitted.

Minimal redacted request or reproduction

1. Use an official Codex client and a sub2api account restricted to official Codex clients. Confirm that the same client, gateway credential, and model work when connected directly to the gateway. A plain curl request is not an equivalent client-fingerprint reproduction.
2. Configure the gateway through OpenCodex using this provider fragment (substitute the real endpoint and credential locally):

{
  "adapter": "openai-responses",
  "baseUrl": "https://gateway.example.test/v1",
  "authMode": "key",
  "apiKey": "<redacted>",
  "responsesPath": "/responses",
  "forwardClientHeaders": [
    "originator", "x-client-request-id", "x-codex-app-version", "user-agent"
  ]
}

3. Point the official Codex client at OpenCodex's local endpoint, select the same model through that provider, and send a minimal request such as Reply only OK. Affected models in this installation were gpt-6-astra and gpt-6.1-sol.
4. Observe HTTP 403. Repeat with Responses WebSocket disabled: the HTTP request still fails.
5. Try adding x-codex-window-id to forwardClientHeaders: configuration validation rejects it as outside the supported metadata allowlist.

Actual response or error

HTTP 403 Forbidden
{"error":{"message":"This account only allows Codex official clients","type":"forbidden_error"}}

The downstream failure also includes a response.failed event with upstream_error / Upstream request failed. Request IDs, client identifiers, credentials, and private conversation content are omitted.

Upstream documentation

• Related sub2api report identifying a stripped x-codex-window-id: https://github.com/Wei-Shaw/sub2api/issues/4694
• Related relay metadata fix (merged July 22, 2026): https://github.com/Wei-Shaw/sub2api/pull/4696
• Configurable engine fingerprint implementation: https://github.com/Wei-Shaw/sub2api/blob/main/backend/internal/pkg/openai/engine_fingerprint_signal.go

The gateway's deployed fingerprint configuration is not publicly available. The direct/proxied comparison, captured inbound header names, allowlist behavior, and local patched result are the evidence for this report; it does not assume every sub2api deployment has identical policy.

Suggested mapping or implementation notes

Extend the existing explicit metadata allowlist with x-codex-window-id and x-codex-installation-id. Reuse the existing Responses and native compact/fallback metadata copying, rather than introducing a second forwarding policy. Keep opt-in per provider and per header, preserve provider-header precedence, and continue rejecting credentials, attestations, assertions, and arbitrary header prefixes.

This is pass-through of real caller metadata only. It should not assign an official-client identity to connection tests, model discovery, or other proxy-originated requests.

Additional context and attachments

A local patch allowing the two named identifiers, together with explicit provider opt-in, restored the official CLI requests for both affected models. The desktop user has also confirmed that the original workflow now works after the local patch. A source PR with regression tests and configuration documentation will follow.

Checks

• I searched existing provider and compatibility issues.
• The request and response were redacted.
• The expected behaviour is based on an upstream specification or a concrete client requirement.