sub2api codex_cli_only rejects official Codex requests after client identifiers are stripped

Open
  • Is something wrong?
#8,192 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@ParsifalC is already working on this.

Since Nov 5, 2026.

  • #8193 by @ParsifalC — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
api, backend

Research direction

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.

Written by the indexing model from the issue text.

Description

provider provider-compatibility streaming
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"
  ]
}
  1. 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.
  2. Observe HTTP 403. Repeat with Responses WebSocket disabled: the HTTP request still fails.
  3. 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

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.
Dominant language
TypeScript
Stars
16.9k
Forks
1.3k
Avg merge
19h 24m
Merged PRs (30d)
676

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lidge-jun/opencodex

All issues in lidge-jun/opencodex

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.