[Docs] Codex integration silently requires an upstream that implements the Responses API; MemoryProxy forwards /v1/responses without translation

agents/codex/README.md tells users to set wire_api = "responses" but never states the consequence: the upstream behind MemoryProxy must itself implement the OpenAI Responses API. The proxy forwards /v1/responses verbatim and does no protocol translation, so any OpenAI-compatible upstream that only implements /v1/chat/completions — which is most of them — cannot serve Codex, and the failure surfaces as a bare 404/400 from the upstream with nothing pointing at the real cause.

Version: 906b582 (branch feat/server_team, 2026-09-11)

Where it is known in the code but not in the docs

MemoryProxy/src/codexHandler.ts:1097-1100:

// Per-agent upstream override (upstream.agents.codex.url) 优先于全局 url。
// 对齐 anthropicHandler.ts:1029 的解析姿势。codex 通常需要单独指向支持
// Responses API 的兼容层——部分 OpenAI 兼容上游只实现
// messages/chat_completions，不支持 /responses，此处允许按 agent 覆盖。

The code comment states the requirement plainly and even explains why the per-agent override exists. None of that reaches the user:

• agents/codex/README.md §1 documents wire_api, base_url and experimental_bearer_token, and explains disable_response_storage and stream_idle_timeout_ms — but says nothing about what the upstream must support.
• config.example.yaml's upstream.agents block explains the url/apiKey fallback matrix, but presents the per-agent override purely as a credential/routing feature, not as the remedy for a protocol mismatch.

Reproduction

1. Follow agents/codex/README.md §1 exactly.
2. Set upstream.url to any OpenAI-compatible gateway that exposes /v1/chat/completions and /v1/models but not /v1/responses (in my case a local gateway serving an Anthropic-family model; it also exposes /v1/messages, so the Claude Code path through the same proxy works fine).
3. Start a Codex session.

The Anthropic path through the same proxy and the same upstream works; only Codex fails, and the error comes from the upstream, so nothing in it suggests that the documented Codex configuration has an unstated requirement.

Why this is worth fixing rather than just knowing

Both official coding-agent integrations are documented as if they have the same upstream requirements, and they do not:

Responses API support is still much rarer than chat/completions among OpenAI-compatible gateways, so a user who successfully set up Claude Code against their own upstream will reasonably expect Codex to work against it too, and has no way to find out otherwise short of reading codexHandler.ts.

Suggested fix

Either of these would have saved the investigation; the first is cheap:

1. Document it. Add a line to agents/codex/README.md §1 stating that the upstream must implement the Responses API, that chat/completions-only upstreams are not supported on this path, and that upstream.agents.codex.url is the intended escape hatch for pointing Codex at a different compatibility layer.

2. Fail loudly. On an upstream 404/400 for /v1/responses, log a specific hint (upstream does not appear to implement the Responses API; see upstream.agents.codex.url) instead of surfacing the raw upstream error. Cheap, and it turns a dead end into a pointer.

3. Optional, larger: translate Responses → chat/completions when the upstream does not support the former. This would widen compatible-upstream coverage a lot, but it is a real feature and the two above are worth doing regardless.

Environment: macOS 15 (arm64), Node 22.22.3, MemoryProxy from 906b582.