[Feature Request] Complete the external aggregated model API for third-party agents #357

Summary

OpenCodex already aggregates multiple upstream sources, including ChatGPT/Codex account pools, OAuth/API-key providers, OpenAI-compatible relay services, Anthropic, Gemini, OpenRouter, Ollama, and combo/failover routes.

It would be valuable to expose these resources as a complete, general-purpose model gateway for third-party AI agents—not only for Codex and Claude Code.

The dashboard currently provides an API Access page where users can generate an ocx_... API key. However, the external API experience is incomplete, especially for clients that need to discover and select models.

Intended use case

A user may have multiple ChatGPT accounts in the OpenCodex account pool, plus several relay services and providers configured in OpenCodex.

The expected architecture is:

Third-party agent
        |
        | Unified OpenAI-compatible API
        v
     OpenCodex
        |
        +-- ChatGPT/Codex account pool
        +-- OpenRouter
        +-- Third-party relay services
        +-- Anthropic / Gemini / xAI
        +-- Local models

The third-party agent should only need one OpenCodex endpoint and one OpenCodex API key. It should be able to retrieve the aggregated model list and select models such as:

gpt-5.x
anthropic/claude-...
google/gemini-...
openrouter/...
combo/...

OpenCodex would then select the correct provider, credential, or ChatGPT pool account internally.

Current behavior and limitations

OpenCodex already exposes:

• GET /v1/models
• POST /v1/responses
• POST /v1/messages
• Image, search, and compaction endpoints

It also routes provider/model IDs to configured providers. However, several limitations prevent it from working as a general aggregated gateway.

1. No inbound Chat Completions endpoint

Many third-party agents only support:

POST /v1/chat/completions

OpenCodex supports Chat Completions providers internally, but it does not expose /v1/chat/completions to external clients. Requests to that endpoint return 404.

The current wording can be confusing: support for OpenAI-compatible Chat Completions providers describes the OpenCodex-to-upstream direction, not necessarily the client-to-OpenCodex direction.

2. The API Access page does not expose the model catalog

The page allows users to generate API keys, but it does not clearly show:

• All externally callable models
• Exact model IDs to send
• Which provider owns each model
• Which inbound protocol supports each model
• Whether a model uses the ChatGPT account pool
• Whether a model is a combo/failover route

Users can generate a key but may not know how to select any model other than a default one.

3. Limited compatibility with third-party model selectors

Some third-party clients:

• Only support /v1/chat/completions
• Do not query /v1/models
• Reject or mishandle model IDs containing /
• Only accept an OpenAI base URL and bearer token
• Cannot add a custom x-opencodex-api-key header

This prevents many agents from using OpenCodex's aggregated models.

4. Authentication documentation is inconsistent

The API Access page says clients may use either:

Authorization: Bearer ocx_...

or:

x-opencodex-api-key: ocx_...

However, remote authentication for /v1/responses specifically requires x-opencodex-api-key, because the Authorization header may belong to Codex Direct passthrough.

The UI should clearly explain this behavior, or external gateway authentication should be made consistent where safely possible.

5. Local and remote behavior is unclear

Authentication is bypassed for loopback binds. For non-loopback binds, an OPENCODEX_API_AUTH_TOKEN environment variable is required even when generated ocx_... client keys already exist.

The relationship between the master environment token and generated client keys should be documented on the API Access page.

Proposed improvements

Protocol compatibility

Add an inbound:

POST /v1/chat/completions

It could translate Chat Completions requests into the existing internal Responses pipeline and translate the result back. Both streaming and non-streaming responses should be supported.

Model catalog in the dashboard

Extend the API Access page with:

• Model ID and display name
• Provider/source
• Supported inbound protocols
• Context window and availability
• Account-pool/API-provider/combo designation
• Copy-model-ID action
• Simple test-request action

Clear client configuration

Provide separate examples for:

• OpenAI Responses API
• OpenAI Chat Completions API
• Anthropic Messages API
• OpenAI SDK
• Anthropic SDK
• Generic third-party agents

Clearly distinguish a base URL such as:

http://127.0.0.1:10100/v1

from a full endpoint such as:

http://127.0.0.1:10100/v1/responses

Authentication consistency and scopes

Either support Authorization: Bearer ocx_... consistently for external gateway traffic while preserving Codex Direct safely, or clearly require x-opencodex-api-key for Responses requests.

Generated keys could eventually support:

• Inference-only versus management access
• Model allowlists
• Expiration
• Request/usage limits
• Per-key usage visibility

Expected result

A third-party agent should be able to:

1. Configure one OpenCodex base URL.
2. Authenticate with one generated OpenCodex key.
3. Retrieve aggregated models from /v1/models.
4. Select any available provider/model, native GPT, or combo model.
5. Send either Responses or Chat Completions requests.
6. Let OpenCodex privately manage provider credentials and ChatGPT account-pool selection.

No upstream credentials or individual ChatGPT account details should need to be exposed to the external agent.

Suggested acceptance criteria

• POST /v1/chat/completions supports streaming and non-streaming requests.
• Tool calls and reasoning fields degrade safely during protocol conversion.
• GET /v1/models returns stable, externally callable model IDs.
• Every listed model can be tested from the API Access page.
• The API Access page explains model selection and protocol compatibility.
• Authentication instructions match actual endpoint behavior.
• ChatGPT account-pool selection remains automatic and internal.
• Existing Codex and Claude Code behavior remains backward compatible.

Why this matters

OpenCodex already contains most of the difficult provider routing, protocol translation, account-pool, model-discovery, and failover logic.

Completing the external API layer would make it a useful local model aggregation gateway for a much wider ecosystem of agents and automation tools without exposing or duplicating upstream credentials.