Document promptCacheKey opt-in for compatible custom openai-chat providers #2536

Documentation problem type

Missing documentation

Documentation location

https://opencodex.me/reference/configuration/providers/

What is wrong or missing?

The custom openai-chat provider reference does not document the per-provider promptCacheKey capability flag or explain that it controls forwarding of an inbound prompt_cache_key to the upstream Chat Completions request.

The conditional forwarding added in #217 and #224 works correctly. The missing documentation makes the opt-in difficult to discover, so a compatible custom provider may silently receive no stable cache-affinity key even though Codex supplies one.

This had a measurable effect with an anonymous OpenAI-compatible custom provider on OpenCodex 2.31.0. Before the opt-in, 12 natural requests contained 976,572 input tokens and 9,216 cached input tokens, an aggregate cache ratio of 0.94%, with 10 zero-cache requests. After adding only promptCacheKey: true and restarting OpenCodex, 28 natural requests contained 2,327,714 input tokens and 1,943,552 cached input tokens, an aggregate cache ratio of 83.50%, with no HTTP errors. Excluding the first cold request in each of two conversations, the aggregate ratios were 95.66% and 86.89%, with no subsequent zero-cache requests.

API-key rotation, proxy retries or duplicate sends, usage telemetry mismatch, helper routing, and Codex local-memory toggling were checked and did not explain the difference.

What should the documentation explain instead?

The custom-provider reference should explain that:

• promptCacheKey: true is an explicit compatibility opt-in for openai-chat providers that accept OpenAI's prompt_cache_key field.
• When enabled, OpenCodex forwards the stable key supplied by the client; when absent or false, it omits the field.
• The option is deliberately not a global default because strict OpenAI-compatible gateways may reject unknown fields with HTTP 400.
• Users should enable it only for a provider with confirmed support, preserve the rest of the provider configuration, restart or reload OpenCodex as required, and remove the option if the upstream reports an unknown-field error.
• Cache validation should distinguish the first cold request from later requests in the same conversation.

Suggested wording or example

For a custom Chat Completions provider that explicitly supports prompt_cache_key:

{
  "providers": {
    "example-compatible-provider": {
      "adapter": "openai-chat",
      "promptCacheKey": true
    }
  }
}

promptCacheKey is disabled by default for custom providers. Enable it only when the upstream accepts prompt_cache_key; otherwise a strict gateway may return HTTP 400. Existing baseUrl, authentication, model, and key-pool fields should remain unchanged.

Additional context or attachments

• [Bug]: Forward prompt_cache_key through the openai-chat adapter #217 introduced preservation and forwarding support.
• fix(adapters): forward prompt_cache_key through openai-chat adapter (#217) #224 implemented the provider-gated behavior.
• feat(kimi): forward prompt_cache_key on the Kimi Coding Plan presets #597 demonstrates the provider-registry opt-in pattern for a known-compatible preset.
• This report requests documentation only, not a global default change or a new adapter behavior.
• Provider identity, endpoint, request bodies, local paths, conversation identifiers, and credentials are intentionally omitted.
• No synthetic paid traffic was generated; both samples came from natural traffic.

Checks

• I searched existing documentation issues.
• No secrets or personal information are included.