fix(api): enforce API_TIMEOUT_MS for OpenAI-compatible headers

.env.example

@@ -423,8 +423,15 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 # Turn on whichever audience you're debugging; both can run together.
 # OPENCLAUDE_LOG_TOKEN_USAGE=verbose
 
-# Custom timeout for API requests in milliseconds (default: varies)
-# API_TIMEOUT_MS=60000
+# Time-to-response-headers deadline for OpenAI-compatible API requests
+# in milliseconds (default: 600000, or 10 minutes). Use a safe positive
+# integer; invalid values use the default and values above 2147483647 are capped.
+# This runtime setting must be exported from your shell or launcher; the
+# provider env-file loader intentionally ignores runtime/debug knobs.
+# This covers generic OpenAI-compatible requests, direct GitHub Copilot
+# Responses, and Copilot chat-to-Responses fallback requests. First-party
+# Codex OAuth Responses and the Anthropic SDK retain their existing handling.
+# API_TIMEOUT_MS=600000
 
 # Enable debug logging
 # CLAUDE_DEBUG=1

docs/advanced-setup.md

@@ -437,6 +437,7 @@ token; do not set both credentials.
 | `OPENAI_MODEL` | OpenAI-compatible only | Model name such as `gpt-4o`, `deepseek-v4-flash`, or `llama3.3:70b` |
 | `OPENAI_BASE_URL` | No | API endpoint, defaulting to `https://api.openai.com/v1` |
 | `OPENAI_API_BASE` | No | Compatibility alias for `OPENAI_BASE_URL` |
+| `API_TIMEOUT_MS` | No | Time-to-response-headers deadline for generic OpenAI-compatible requests, direct GitHub Copilot Responses, and Copilot chat-to-Responses fallback requests, in milliseconds (default: `600000`, or 10 minutes). The value must be a safe positive integer; invalid, zero, negative, or fractional values use the default, and values above `2147483647` are capped. The deadline is disarmed after headers arrive, so it does not limit response streaming. Export this runtime setting from your shell or launcher. First-party Codex OAuth Responses and the Anthropic SDK retain their existing timeout handling. |
 | `OPENCLAUDE_OLLAMA_NUM_CTX` | Ollama only | Request-level Ollama context window. Defaults to `32768`; set a larger value for longer same-session history if your model and hardware can handle it. |
 | `CLAUDE_CODE_OPENAI_CONTEXT_WINDOWS` | No | JSON map of OpenAI-compatible model names to context windows, such as `{"custom-model":1000000}`. Use this when a custom provider does not expose context metadata from `/v1/models`. |
 | `CLAUDE_CODE_OPENAI_MAX_OUTPUT_TOKENS` | No | JSON map of OpenAI-compatible model names to max output tokens, such as `{"custom-model":32768}`. Use this when a custom provider does not expose output-limit metadata from `/v1/models`. |

src/services/api/codexShim.ts

@@ -600,6 +600,7 @@ export async function performCodexRequest(options: {
   params: ShimCreateParams
   defaultHeaders: Record<string, string>
   signal?: AbortSignal
+  fetcher?: typeof fetchWithProxyRetry
 }): Promise<Response> {
   const compressedMessages = compressToolHistory(
     options.params.messages as Array<{
@@ -678,7 +679,7 @@ export async function performCodexRequest(options: {
   }
   headers.originator ??= 'openclaude'
 
-  const response = await fetchWithProxyRetry(
+  const response = await (options.fetcher ?? fetchWithProxyRetry)(
     `${options.request.baseUrl}/responses`,
     {
       method: 'POST',

src/services/api/fetchWithProxyRetry.test.ts

@@ -143,3 +143,72 @@ test('fetchWithProxyRetry retries and disables keepalive after receiving a 504 r
   expect((calls[0] as RequestInit).keepalive).toBeUndefined()
   expect((calls[1] as RequestInit).keepalive).toBe(false)
 })
+
+test('fetchWithProxyRetry does not retry a 504 after the request is aborted', async () => {
+  const controller = new AbortController()
+  const abortReason = new DOMException('Deadline exceeded', 'TimeoutError')
+  let attempts = 0
+
+  globalThis.fetch = (async () => {
+    attempts++
+    controller.abort(abortReason)
+    return new Response('Gateway Timeout', { status: 504 })
+  }) as unknown as FetchType
+
+  await expect(
+    fetchWithProxyRetry('https://example.com/generate', {
+      method: 'POST',
+      signal: controller.signal,
+    }),
+  ).rejects.toBe(abortReason)
+
+  expect(attempts).toBe(1)
+})
+
+test('fetchWithProxyRetry preserves the abort reason for a generic fetch failure', async () => {
+  for (const message of ['fetch failed', 'invalid_argument']) {
+    const controller = new AbortController()
+    const abortReason = new DOMException('Deadline exceeded', 'TimeoutError')
+    let attempts = 0
+
+    globalThis.fetch = (async () => {
+      attempts++
+      controller.abort(abortReason)
+      throw new TypeError(message)
+    }) as unknown as FetchType
+
+    await expect(
+      fetchWithProxyRetry('https://example.com/generate', {
+        method: 'POST',
+        signal: controller.signal,
+      }),
+    ).rejects.toBe(abortReason)
+
+    expect(attempts).toBe(1)
+  }
+})
+
+test('fetchWithProxyRetry preserves an explicit AbortError from fetch', async () => {
+  const controller = new AbortController()
+  const abortReason = new DOMException('Caller cancelled', 'AbortError')
+  const fetchAbortError = new DOMException(
+    'The operation was aborted.',
+    'AbortError',
+  )
+  let attempts = 0
+
+  globalThis.fetch = (async () => {
+    attempts++
+    controller.abort(abortReason)
+    throw fetchAbortError
+  }) as unknown as FetchType
+
+  await expect(
+    fetchWithProxyRetry('https://example.com/generate', {
+      method: 'POST',
+      signal: controller.signal,
+    }),
+  ).rejects.toBe(fetchAbortError)
+
+  expect(attempts).toBe(1)
+})

src/services/api/fetchWithProxyRetry.ts

@@ -29,6 +29,12 @@ export async function fetchWithProxyRetry(
           forAnthropicAPI: options?.forAnthropicAPI,
         }),
       })
+      if (init?.signal?.aborted) {
+        throw (
+          init.signal.reason ??
+          new DOMException('The operation was aborted.', 'AbortError')
+        )
+      }
 
       // If an upstream proxy or local NAT silently dropped the keep-alive socket,
       // it might result in a 502/504 response instead of a hard network exception.
@@ -44,7 +50,15 @@ export async function fetchWithProxyRetry(
       return response
     } catch (error) {
       lastError = error
-      if (attempt >= maxAttempts || !isRetryableFetchError(error)) {
+      if (init?.signal?.aborted) {
+        throw error instanceof Error && error.name === 'AbortError'
+          ? error
+          : (init.signal.reason ?? error)
+      }
+      if (
+        attempt >= maxAttempts ||
+        !isRetryableFetchError(error)
+      ) {
         throw error
       }
       disableKeepAlive()

src/services/api/openaiErrorClassification.ts

@@ -27,6 +27,28 @@ export type OpenAICompatibilityFailure = {
   requestUrl?: string
 }
 
+const NON_REPLAYABLE_OPENAI_REQUEST = Symbol.for(
+  'openclaude.openai.nonReplayableRequest',
+)
+
+export function markOpenAIRequestNonReplayable<T extends object>(error: T): T {
+  Object.defineProperty(error, NON_REPLAYABLE_OPENAI_REQUEST, {
+    value: true,
+    configurable: false,
+    enumerable: false,
+    writable: false,
+  })
+  return error
+}
+
+export function isOpenAIRequestNonReplayable(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    Reflect.get(error, NON_REPLAYABLE_OPENAI_REQUEST) === true
+  )
+}
+
 const OPENAI_CATEGORY_MARKER_PREFIX = '[openai_category='
 
 const LOCALHOST_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1'])