AI-assisted (Claude Opus 4.6), driven by a maintainer. Fully tested — see Human Verification and the AI-assisted disclosure section below.

Summary

• Problem: the strip added in fix: strip prompt_cache_key for non-OpenAI openai-responses endpoints #49877 (fixing [Bug]: prompt_cache_key not supported by Volcano Engine DeepSeek #48155 — Volcano Engine DeepSeek rejects prompt_cache_key with HTTP 400) applies to every non-native baseUrl via the usesExplicitProxyLikeEndpoint gate, including OpenAI-compatible proxies that DO forward the field correctly (CLIProxy, LiteLLM, vLLM). Agents routed through those proxies get zero prompt caching as a side effect.
• Why it matters: operators running agents through an OpenAI-compatible proxy see cached_tokens: 0 on every turn even with stable sessions and large repeating prefixes. On a ~40K-token prefix, that's ~40K uncached input tokens re-sent on each turn — wasted latency and wasted spend (or quota pressure on subscription-backed routes like Codex Plus).
• What changed: add compat.supportsPromptCacheKey?: boolean to ModelCompatConfig and extend resolveProviderRequestCapabilities to let operators override the strip per model. undefined preserves the existing default so [Bug]: prompt_cache_key not supported by Volcano Engine DeepSeek #48155 continues to work without any config change. true opts out of the strip for proxies known to be compatible. false forces the strip for endpoints known to reject the field, even on native baseUrls.
• What did NOT change (scope boundary): default behavior is unchanged for every existing config; prompt caching on direct OpenAI / Azure OpenAI / OpenAI Codex native endpoints is unchanged; Anthropic cacheRetention is in a different code path and unaffected; the createOpenAIResponsesContextManagementWrapper in openai-stream-wrappers.ts is not modified — the new flag plugs into the already-computed shouldStripResponsesPromptCache capability.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration
• API / contracts

Linked Issue/PR

• Related [Bug]: prompt_cache_key not supported by Volcano Engine DeepSeek #48155, fix: strip prompt_cache_key for non-OpenAI openai-responses endpoints #49877 (original strip — preserved as the default in this PR)
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the strip's gating condition (api ∈ OPENAI_RESPONSES_APIS && policy.usesExplicitProxyLikeEndpoint) is an upper bound on "endpoints that might reject the field", not a proxy allowlist. It catches a much wider set of proxies than the specific ones known to be incompatible. A per-model opt-out is the minimum mechanism to let operators re-enable caching for known-good proxies without changing the conservative default.
• Missing detection / guardrail: there's no existing capability for the operator to express "my proxy handles this field fine, don't strip it." Related compat flags exist (supportsStore, supportsDeveloperRole, etc.) but none for prompt_cache_key.
• Contributing context (if known): the strip was introduced as a point fix for one specific provider (Volcano Engine DeepSeek). Since the proxy-like heuristic is the easiest available signal, it generalized to all non-native endpoints. The cost of that generalization only became visible to operators whose proxies DO forward the field and who were watching cached_tokens closely.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/agents/provider-attribution.test.ts
• Scenario the test should lock in: shouldStripResponsesPromptCache respects the new compat.supportsPromptCacheKey override (true, false, undefined) independently of endpoint class.
• Why this is the smallest reliable guardrail: resolveProviderRequestCapabilities is the single computation site for the strip flag, and the existing tests in this file already cover the endpoint-class cases that feed it. Extending that file keeps the test surface tight and adjacent to the code change.
• Existing test that already covers this (if any): no — the existing tests on line 619 (shouldStripResponsesPromptCache: true on a custom-proxy endpoint) only cover the default-strip path, not the override. The new it("respects compat.supportsPromptCacheKey override on prompt cache stripping", ...) block covers all three override states and the preserved default.
• If no new test is added, why not: N/A — 3 new test cases added.

User-visible / Behavior Changes

• New optional config field: agents.defaults.models.<provider>/<model>.compat.supportsPromptCacheKey?: boolean.
• Default behavior is unchanged. Operators who do not set the new field see the exact same behavior as before this PR.
• Operators using OpenAI-compatible proxies that forward prompt_cache_key correctly can set supportsPromptCacheKey: true on their model compat block and recover prompt caching (non-zero cached_tokens in usage responses).
• Operators who know a native endpoint rejects the field can set supportsPromptCacheKey: false to force the strip even on native baseUrls.

Diagram (if applicable)

Before (this PR does NOT change this path when compat flag is undefined):
  [operator config]
       |
       v
  baseUrl not in {api.openai.com, chatgpt.com, azure.openai.com} ?
       |
       v ( yes )
  usesExplicitProxyLikeEndpoint = true
       |
       v
  shouldStripResponsesPromptCache = true   (for every proxy, incl. compatible ones)
       |
       v
  payload stripped -> cached_tokens = 0 every turn

After (new compat.supportsPromptCacheKey override):
  [operator config: compat.supportsPromptCacheKey = true]
       |
       v
  shouldStripResponsesPromptCache = false   (override wins; key forwarded)
       |
       v
  payload preserved -> cached_tokens > 0 on repeat prefixes

  [operator config: compat.supportsPromptCacheKey = false]
       |
       v
  shouldStripResponsesPromptCache = true    (forced; even on native endpoints)

  [operator config: compat.supportsPromptCacheKey undefined]
       |
       v
  (existing behavior preserved — strip only on proxy-like responses endpoints)

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No (adds a conditional pass-through of an existing OpenAI Responses field; no new outbound requests, no new auth paths)
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux (Ubuntu 24.04, via Docker host)
• Runtime/container: Node 24, ghcr.io/openclaw/openclaw:latest base image
• Model/provider: openai-codex with openai-codex-responses API, OAuth-authed ChatGPT Plus subscription
• Integration/channel (if any): Telegram bot channel and local openclaw agent --message CLI
• Relevant config (redacted):

  {
    "agents": {
      "list": [{
        "id": "<redacted>",
        "models": [{ "model": "openai-codex/gpt-5.4" }]
      }],
      "defaults": {
        "models": {
          "openai-codex/gpt-5.4": {
            "baseUrl": "http://<redacted-proxy-host>:8417",
            "compat": {
              "supportsPromptCacheKey": true
            }
          }
        }
      }
    }
  }

Steps

1. Run an OpenClaw agent with baseUrl pointing at an OpenAI-compatible proxy (e.g. CLIProxy). Use any OpenAI Responses API model (openai-responses, openai-codex-responses, azure-openai-responses).
2. Issue three consecutive turns on the same session with a prefix ≥1K tokens so prompt caching is eligible.
3. Inspect usage.input_tokens_details.cached_tokens on each response (or agentMeta.lastCallUsage.cacheRead in the openclaw agent --json output).

Expected

• Before this PR OR with supportsPromptCacheKey unset: cached_tokens = 0 on every turn.
• With supportsPromptCacheKey: true: cached_tokens > 0 from turn 2 onward (proportional to shared prefix length), subject to OpenAI's documented 1024-token minimum and cache TTL.

Actual

Matches expected. Numbers below.

Evidence

• Trace/log snippets
• Perf numbers (if relevant)

Live A/B on a running agent with a ~40K-token shared prefix, 3 consecutive turns per phase, ~10s spacing, same session across both phases:

Turn 3 under the opt-out: cached_tokens / effective_prefix ≈ 99.7%. Visible input_tokens drops to 127 (from 39937 baseline). Warm-turn wall time is ~18% faster than baseline once the cache is primed. Turn 1 is slower than baseline because the cache is being populated from nothing — this is expected one-time warm-up cost.

Payload instrumentation on the running agent (one log entry per applyOpenAIResponsesPayloadPolicy invocation) confirmed that the session-derived prompt_cache_key was being constructed upstream correctly (keyValue: "<stable-session-id>" on every turn) and deleted by the wrapper under the existing default (stripFires: true). The new opt-out prevents the delete.

Full test lane result

pnpm build && pnpm check && pnpm test run locally on this branch. build and check exit 0 clean. pnpm test surfaced 24 failing test files across the project matrix, all categorized and verified as unrelated to this change:

The 5 files I changed are exercised by provider-attribution.test.ts (27/27 green, including 3 new cases) and openai-responses-payload-policy.test.ts (4/4 green).

Human Verification (required)

• Verified scenarios:
  • Default path (no compat flag) — reproduces the pre-PR behavior bit-for-bit; shouldStripResponsesPromptCache still true on proxy-like responses endpoints, still false on native endpoints.
  • supportsPromptCacheKey: true on a proxy-like endpoint — strip disabled; cached_tokens > 0 confirmed in live usage responses AND OpenClaw's agentMeta.lastCallUsage.cacheRead on the next turn.
  • supportsPromptCacheKey: false on a native endpoint — strip forced; confirmed via the unit test (live verification was not needed for this branch — it is a defensive future-proofing path).
  • Full A/B on a production-shaped 40K-token prefix (table above).
• Edge cases checked:
  • compat object entirely absent (type allows this).
  • compat.supportsPromptCacheKey explicitly undefined vs omitted.
  • Interaction with compat.supportsStore (independent flag, no interference — verified by reading the now-adjacent branches in resolveProviderRequestCapabilities).
• What I did NOT verify:
  • Non-OpenAI provider paths (Anthropic, Google, Bedrock) — the change is scoped to shouldStripResponsesPromptCache, which only affects OpenAI Responses APIs, but I have not exhaustively grepped for side effects.
  • codex review --base origin/main — no Codex access. The PR author will run this before submitting.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — default behavior unchanged; existing configs keep working identically.
• Config/env changes? No required, Yes optional — operators MAY add compat.supportsPromptCacheKey to opt out of the strip.
• Migration needed? No. Upgrade steps: none. Operators on affected proxies can optionally set the new flag after upgrading.

Risks and Mitigations

• Risk: An operator sets supportsPromptCacheKey: true on a proxy that actually rejects prompt_cache_key, resulting in the original [Bug]: prompt_cache_key not supported by Volcano Engine DeepSeek #48155-style HTTP 400s.
  • Mitigation: this is an explicit opt-in per model; the default is unchanged and protects users who do nothing. The new field's behavior is documented in the commit message and this PR description. Operators opting in should observe their upstream provider's behavior before deploying broadly.
• Risk: An operator sets supportsPromptCacheKey: false on a native OpenAI endpoint that would have cached, losing the cache benefit.
  • Mitigation: this is also explicit opt-in; the default remains unchanged. The false branch is defensive future-proofing — no known operator needs it today.

AI-assisted disclosure

• Marked as AI-assisted in the title/description: yes
• Degree of testing: fully tested — the new code path is covered by 3 new unit tests, the surrounding resolveProviderRequestCapabilities suite is unchanged (27/27 passing), and the change was additionally validated end-to-end against a live OpenAI-Codex agent via a live-patch A/B (see Evidence).
• Session logs: available on request. The work was driven by a maintainer via an LLM coding assistant (Claude Opus 4.6) and instructed to resolve any bot review conversations it addresses.
• Contributor confirms understanding of the code: yes. The change adds one optional boolean to a compat schema, plugs it into one capability computation, and regenerates the generated JSON schema mirror.