fix(images): support custom relay providers

iF2007 · web-flow · commit 14ae6fe991c3 · 2026-07-27T22:39:58.000+09:00
Merge PR #551 after current-head verification.\n\nEvidence:\n- head f51b64a is based on dev 261abb7\n- bun test tests/server-images.test.ts: 28 pass / 0 fail\n- bun x tsc --noEmit: pass\n- bun run privacy:scan: pass\n- git diff --check origin/dev...HEAD: pass\n- pre-push equivalent gate on local same-behavior patch: root tests 5066 pass / 0 fail, GUI lint pass, React Doctor no issues\n\nThe stale CHANGES_REQUESTED review named blockers that are now fixed on the current head.
diff --git a/docs-site/src/content/docs/guides/codex-integration.md b/docs-site/src/content/docs/guides/codex-integration.md
@@ -42,11 +42,39 @@ points at opencodex, the proxy relays those calls to the OpenAI upstream:
   caller OAuth bearer. The configured mode applies consistently to the image request.
 - **OpenAI API-key provider:** it is used only when no forward candidate owns an authentication
   failure. A broken/expired Pool credential is never hidden behind separately billed API usage.
+- **Explicit custom provider:** set `images.provider` to the id of a custom API-key
+  `openai-responses` provider whose endpoint implements the OpenAI Images API. Explicit selection
+  fails closed and never falls back to a different paid upstream. Registry-managed provider ids
+  are not accepted here; omit `images.provider` to use the built-in OpenAI tiers.
 - **Neither:** the proxy returns a clear error instead of a generic 404. Routed providers
   (Cursor, Gemini, Kiro, …) cannot serve image generation; if you don't want the tool offered at
   all, disable it in Codex with `codex features disable image_generation`
   (`[features] image_generation = false` in `config.toml`).
 
+For an OpenAI-compatible custom gateway, configure a dedicated provider and select it only for
+standalone Images requests:
+
+```json
+{
+  "providers": {
+    "custom-images": {
+      "adapter": "openai-responses",
+      "baseUrl": "https://gateway.example.com/v1",
+      "authMode": "key",
+      "apiKey": "${IMAGE_GATEWAY_API_KEY}"
+    }
+  },
+  "images": {
+    "provider": "custom-images",
+    "timeoutMs": 300000
+  }
+}
+```
+
+The custom endpoint must accept `POST /v1/images/generations` and `/v1/images/edits` and return the
+OpenAI Images response shape expected by Codex. The provider's configured key replaces any caller
+bearer before the upstream request.
+
 For a non-loopback `hostname`, Codex must send the generated API auth header. The injector therefore
 uses a dedicated provider instead:
 
diff --git a/docs-site/src/content/docs/ja/guides/codex-integration.md b/docs-site/src/content/docs/ja/guides/codex-integration.md
@@ -41,8 +41,12 @@ ChatGPT bearer 認証で直接 POST します。注入された `base_url` が o
   bearer を使います。設定されたモードは画像リクエストにも同じく適用されます。
 - **OpenAI API キー:** forward 候補が認証失敗を所有しないときのみ使います。壊れた Pool 認証を
   別課金 API 使用で隠しません。
+- **明示的なカスタムプロバイダー:** `images.provider` に、OpenAI Images API を実装するカスタムの
+  API キー方式 `openai-responses` プロバイダーを指定できます。明示的な選択が失敗しても、別の
+  有料上流へフォールバックしません。組み込みプロバイダー id には使わず、既定の OpenAI 経路を
+  使う場合は省略してください。
 - **両方なし:** 曖昧な 404 の代わりに明確なエラーを返します。ルーティングされる他のプロバイダー(Cursor、
-  Gemini、Kiro など)は画像生成を提供できません。ツール自体をオフにしたい場合は Codex で
+  Gemini、Kiro など)は既定では画像生成を提供できません。ツール自体をオフにしたい場合は Codex で
   `codex features disable image_generation`(`config.toml` の `[features] image_generation = false`)を
   使ってください。
 
diff --git a/docs-site/src/content/docs/ko/guides/codex-integration.md b/docs-site/src/content/docs/ko/guides/codex-integration.md
@@ -41,8 +41,11 @@ ChatGPT bearer 인증으로 직접 POST합니다. 주입된 `base_url`이 openco
   bearer를 사용합니다. 설정된 모드는 이미지 요청에도 동일하게 적용됩니다.
 - **OpenAI API key:** forward 후보가 인증 실패를 소유하지 않을 때만 사용합니다. 깨진 Pool 인증을
   별도 과금 API 사용으로 숨기지 않습니다.
+- **명시적 커스텀 프로바이더:** `images.provider`에 OpenAI Images API를 구현한 커스텀 API-key
+  `openai-responses` 프로바이더를 지정할 수 있습니다. 명시적 선택이 실패해도 다른 유료 업스트림으로
+  fallback하지 않습니다. 내장 프로바이더 id에는 사용하지 말고, 기본 OpenAI 경로를 쓰려면 생략하세요.
 - **둘 다 없음:** 모호한 404 대신 명확한 오류를 반환합니다. 라우팅되는 다른 프로바이더(Cursor,
-  Gemini, Kiro 등)는 이미지 생성을 제공할 수 없습니다. 도구 자체를 끄고 싶다면 Codex에서
+  Gemini, Kiro 등)는 기본적으로 이미지 생성을 제공할 수 없습니다. 도구 자체를 끄고 싶다면 Codex에서
   `codex features disable image_generation`(`config.toml`의 `[features] image_generation = false`)을
   사용하세요.
 
diff --git a/docs-site/src/content/docs/reference/configuration.md b/docs-site/src/content/docs/reference/configuration.md
@@ -62,6 +62,7 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
 | `cacheRetention?` | `"none" \| "short" \| "long"` | `"short"` | Anthropic prompt-cache policy: disabled, 5-minute ephemeral, or 1-hour extended. |
 | `webSearchSidecar?` | `OcxWebSearchSidecarConfig` | on | Web-search sidecar options (see below). |
 | `visionSidecar?` | `OcxVisionSidecarConfig` | on | Vision sidecar options (see below). |
+| `images?` | `OcxImagesConfig` | automatic OpenAI selection | Standalone Images relay options for Codex's built-in `image_gen` tool (see below). |
 | `tokenGuardian?` | `OcxTokenGuardianConfig` | off | Optional proactive OAuth refresh and Codex-account warmup policy; fields are listed below. |
 | `corsAllowOrigins?` | `string[]` | `[]` | Additional exact origins allowed by CORS. Loopback origins are always allowed. |
 
@@ -419,6 +420,17 @@ with those explicit additions, or set it to `false` to expose only `models`.
 
 ## Sidecars
 
+### `images` (`OcxImagesConfig`)
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `provider?` | `string` | automatic OpenAI selection | Explicit custom API-key `openai-responses` provider for `/v1/images/generations` and `/v1/images/edits`. Registry-managed ids are rejected; omit this field to use the built-in ChatGPT/OpenAI fallback. |
+| `timeoutMs?` | `number` | `300000` | Whole-request upstream timeout for one standalone Images request. |
+
+Explicit provider selection fails closed when the provider is missing, disabled, incompatible, or
+has no usable key. It never falls back to another paid upstream. The custom endpoint must implement
+the OpenAI Images API paths and response shape expected by Codex.
+
 ### `webSearchSidecar` (`OcxWebSearchSidecarConfig`)
 
 | Field | Type | Default | Meaning |
diff --git a/docs-site/src/content/docs/ru/guides/codex-integration.md b/docs-site/src/content/docs/ru/guides/codex-integration.md
@@ -46,8 +46,12 @@ fast_mode = true
 - **Провайдер с API-ключом OpenAI:** используется только тогда, когда ни один forward-кандидат
   не «владеет» сбоем аутентификации. Сломанные или истёкшие учётные данные Pool никогда не
   маскируются отдельно оплачиваемым использованием API.
+- **Явный пользовательский провайдер:** в `images.provider` можно указать пользовательский
+  API-key-провайдер `openai-responses`, реализующий OpenAI Images API. Ошибка явного выбора не
+  приводит к fallback на другую платную вышестоящую сторону. Встроенные id провайдеров здесь не
+  используются; чтобы сохранить стандартный путь OpenAI, опустите это поле.
 - **Ни того, ни другого:** прокси возвращает понятную ошибку вместо безликого 404.
-  Маршрутизируемые провайдеры (Cursor, Gemini, Kiro, …) не могут обслуживать генерацию
+  Маршрутизируемые провайдеры (Cursor, Gemini, Kiro, …) по умолчанию не могут обслуживать генерацию
   изображений; если вы вообще не хотите предлагать этот инструмент, отключите его в Codex
   командой `codex features disable image_generation`
   (`[features] image_generation = false` в `config.toml`).
diff --git a/docs-site/src/content/docs/zh-cn/guides/codex-integration.md b/docs-site/src/content/docs/zh-cn/guides/codex-integration.md
@@ -40,8 +40,11 @@ OpenAI 上游：
   OAuth bearer。图像请求遵循同一模式。
 - **OpenAI API key：** 仅当 forward 候选没有拥有认证失败时使用。不会用单独计费的 API 调用掩盖
   损坏或过期的 Pool 凭证。
+- **显式自定义 provider：** 可将 `images.provider` 设为一个自定义 API-key
+  `openai-responses` provider；该 endpoint 必须实现 OpenAI Images API。显式选择失败时不会
+  fallback 到其他付费上游。内置 provider id 不适用于此字段；省略它即可使用默认 OpenAI 路径。
 - **两者都没有：** proxy 返回明确的错误而不是含糊的 404。其他路由提供商（Cursor、Gemini、
-  Kiro 等）无法提供图像生成；如果想完全关闭该工具，可在 Codex 中执行
+  Kiro 等）默认无法提供图像生成；如果想完全关闭该工具，可在 Codex 中执行
   `codex features disable image_generation`（即 `config.toml` 的
   `[features] image_generation = false`）。
 
diff --git a/src/providers/openai-sidecar.ts b/src/providers/openai-sidecar.ts
@@ -15,7 +15,7 @@ import {
   OPENAI_API_PROVIDER_ID,
   OPENAI_CODEX_PROVIDER_ID,
 } from "./openai-tiers";
-import { providerCodexAccountMode } from "./registry";
+import { getProviderRegistryEntry, providerCodexAccountMode } from "./registry";
 
 export interface OpenAiForwardSidecarCandidate {
   providerName: typeof OPENAI_CODEX_PROVIDER_ID;
@@ -32,10 +32,11 @@ export interface ResolvedOpenAiForwardSidecar extends OpenAiForwardSidecarCandid
 export interface OpenAiImagesProviderSelection {
   forwardCandidates: OpenAiForwardSidecarCandidate[];
   keyed?: {
-    providerName: typeof OPENAI_API_PROVIDER_ID;
+    providerName: string;
     provider: OcxProviderConfig;
     apiKey: string;
   };
+  error?: string;
 }
 
 export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiForwardSidecarCandidate[] {
@@ -126,3 +127,46 @@ export function selectOpenAiImagesProvider(config: OcxConfig): OpenAiImagesProvi
   }
   return selection;
 }
+
+/** Resolve an explicit custom Images provider, otherwise preserve the existing OpenAI fallback. */
+export function selectImagesProvider(config: OcxConfig): OpenAiImagesProviderSelection {
+  const configuredProvider = config.images?.provider;
+  if (configuredProvider === undefined) return selectOpenAiImagesProvider(config);
+  if (typeof configuredProvider !== "string" || !configuredProvider.trim()) {
+    return { forwardCandidates: [], error: "images.provider must be a nonblank provider name" };
+  }
+  const providerName = configuredProvider.trim();
+
+  if (getProviderRegistryEntry(providerName)) {
+    return {
+      forwardCandidates: [],
+      error: `images.provider "${providerName}" must name a custom provider; omit it to use built-in OpenAI tiers`,
+    };
+  }
+
+  const provider = Object.prototype.hasOwnProperty.call(config.providers, providerName)
+    ? config.providers[providerName]
+    : undefined;
+  if (!provider) {
+    return { forwardCandidates: [], error: `images.provider "${providerName}" is not configured` };
+  }
+  if (provider.disabled === true) {
+    return { forwardCandidates: [], error: `images.provider "${providerName}" is disabled` };
+  }
+  if (provider.adapter !== "openai-responses" || (provider.authMode !== undefined && provider.authMode !== "key")) {
+    return {
+      forwardCandidates: [],
+      error: `images.provider "${providerName}" must be an API-key openai-responses provider`,
+    };
+  }
+
+  const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+  if (!apiKey) {
+    return { forwardCandidates: [], error: `images.provider "${providerName}" has no usable API key` };
+  }
+
+  return {
+    forwardCandidates: [],
+    keyed: { providerName, provider, apiKey },
+  };
+}
diff --git a/src/server/images.ts b/src/server/images.ts
@@ -7,7 +7,8 @@
  * without a route the tool died on the /v1/* JSON-404 guard. Only an OpenAI-family upstream
  * can serve these endpoints — routed providers (Cursor, Kiro, Gemini, …) have no image
  * generation surface — so the handler relays the body verbatim to the ChatGPT forward
- * provider (or an OpenAI API-key provider) and passes the response through untouched:
+ * provider, an OpenAI API-key provider, or an explicitly selected compatible custom provider and
+ * passes the response through untouched:
  * codex's images client parses `{created, data:[{b64_json}]}` strictly and Debug-prints
  * error bodies into the model-visible failure, so upstream errors must stay legible.
  */
@@ -23,7 +24,7 @@ import { formatCodexProviderForLog } from "../codex/routing";
 import { signalWithTimeout } from "../lib/abort";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig } from "../types";
-import { resolveFirstUsableOpenAiSidecar, selectOpenAiImagesProvider } from "../providers/openai-sidecar";
+import { resolveFirstUsableOpenAiSidecar, selectImagesProvider } from "../providers/openai-sidecar";
 import { readJsonRequestBody } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
 import type { RequestLogContext } from "./request-log";
@@ -47,10 +48,17 @@ export async function handleImages(
   endpoint: ImagesEndpoint,
   logCtx: RequestLogContext,
 ): Promise<Response> {
-  try { validateForwardAdmissionCredential(req.headers, config); }
-  catch (err) {
-    if (err instanceof ForwardAdmissionCredentialError) return formatErrorResponse(401, "authentication_error", err.message);
-    throw err;
+  const candidates = selectImagesProvider(config);
+  if (candidates.error) {
+    return formatErrorResponse(400, "invalid_request_error", candidates.error);
+  }
+  const explicitKeyedProvider = config.images?.provider !== undefined && candidates.keyed !== undefined;
+  if (!explicitKeyedProvider) {
+    try { validateForwardAdmissionCredential(req.headers, config); }
+    catch (err) {
+      if (err instanceof ForwardAdmissionCredentialError) return formatErrorResponse(401, "authentication_error", err.message);
+      throw err;
+    }
   }
   let body: unknown;
   try {
@@ -61,7 +69,6 @@ export async function handleImages(
   const model = (body as { model?: unknown } | null)?.model;
   if (typeof model === "string" && model) logCtx.model = model;
 
-  const candidates = selectOpenAiImagesProvider(config);
   if (candidates.forwardCandidates.length === 0 && !candidates.keyed) {
     // 400, not 5xx: codex retries every 5xx up to 5 total attempts, and this is a permanent
     // configuration state that must surface on the first attempt.
diff --git a/src/types.ts b/src/types.ts
@@ -712,6 +712,8 @@ export interface OcxTokenGuardianConfig {
 }
 
 export interface OcxImagesConfig {
+  /** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */
+  provider?: string;
   /** Upstream timeout (ms) for one /v1/images relay. Default 300000 — generation is slow. */
   timeoutMs?: number;
 }
diff --git a/structure/01_runtime.md b/structure/01_runtime.md
@@ -8,7 +8,7 @@
 | `src/lib/bun-runtime.ts` | Bundled-Bun resolution: `isRealBunBinary()` (size gate vs the ~450-byte placeholder stub), `bundledBunPath()`, `durableBunPath()` (path baked into service/shim artifacts). |
 | `src/cli/index.ts` | `ocx` / `opencodex` CLI: init, start, stop, restore/eject, sync, status, login/logout, gui, service, update. After help/version early exits, ordinary commands run the bounded best-effort Codex-shim auto-restore policy before dispatch. Keeps the `#!/usr/bin/env bun` shebang for from-source dev (`bun run src/cli/index.ts`). |
 | `src/server/index.ts` | Bun server entrypoint: `startServer`, `/v1/responses` HTTP + WebSocket routing, exact `POST /v1/images/generations` and `POST /v1/images/edits` routing, `/v1/models`, `/v1/*` JSON 404 guard, GUI fallback, and facade re-exports for split server modules. |
-| `src/server/images.ts` | Standalone Images data plane: forward-provider selection, Codex account affinity, bounded opaque request relay, single-attempt upstream fetch, pool health recording, and safe response/cancellation relay. |
+| `src/server/images.ts` | Standalone Images data plane: default OpenAI or explicit custom-provider selection, Codex account affinity, bounded opaque request relay, single-attempt upstream fetch, pool health recording, and safe response/cancellation relay. |
 | `src/config.ts` | `~/.opencodex/config.json`, defaults, PID path, env-value resolution, `websocketsEnabled()`. |
 | `src/router.ts` | Provider/model selection before adapter dispatch. |
 | `src/types.ts` | Shared config, parsed request, adapter, and event types. |
diff --git a/structure/04_transports-and-sidecars.md b/structure/04_transports-and-sidecars.md
@@ -47,14 +47,18 @@ Codex's local `image_gen.imagegen` tool makes a second Images request after the
 `POST /v1/images/generations` for generation or `POST /v1/images/edits` for reference-image edits.
 These are standalone Images API routes, not the hosted Responses `image_generation` tool.
 
-`src/server/images.ts` selects only an enabled forward-mode `openai-responses` provider, resolves
-the same thread-affined Codex account as Responses, and relays the bounded opaque body without
-rewriting Codex's JSON edit schema or a compatible multipart body. Each paid Images POST receives
+`src/server/images.ts` uses the existing ChatGPT/OpenAI fallback unless `images.provider` explicitly
+selects a custom API-key `openai-responses` provider. Explicit selection fails closed when the
+provider is missing, disabled, registry-managed, incompatible, or lacks a usable key; it never
+falls through to another paid upstream. The relay accepts bounded JSON generation and edit requests,
+then forwards the decoded JSON without rewriting Codex's edit schema. Each paid Images POST receives
 one upstream attempt; client cancellation aborts the upstream and pool-only failures update the
 existing account-health state. Unknown Images subpaths still reach the JSON `/v1/*` 404 guard.
 
-On non-loopback binds, data-plane authentication and origin policy cover both Images routes just as
-they cover `/v1/responses`; clients must send the configured `x-opencodex-api-key`.
+On non-loopback binds, data-plane authentication and origin policy cover both Images routes. An
+explicit keyed Images provider accepts the proxy admission secret as either an OpenAI-style bearer
+or `x-opencodex-api-key` because the provider key replaces caller authorization before fetch. The
+ChatGPT forward path still requires the dedicated header so its upstream bearer remains distinct.
 
 The API-key `openai-responses` path also prevents the standalone client tool from colliding with the
 hosted Responses tool. When a request declares `image_gen.imagegen` (as a flat function or an
diff --git a/tests/server-images.test.ts b/tests/server-images.test.ts

Original file line number	Diff line number	Diff line change
`@@ -712,6 +712,8 @@ export interface OcxTokenGuardianConfig {`
`712`	`712`	`}`
`713`	`713`
`714`	`714`	`export interface OcxImagesConfig {`
	`715`	`+ /** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */`
	`716`	`+ provider?: string;`
`715`	`717`	`/** Upstream timeout (ms) for one /v1/images relay. Default 300000 — generation is slow. */`
`716`	`718`	`timeoutMs?: number;`
`717`	`719`	`}`