From ee75be0fe7246403374d6f80b5ac27a400810989 Mon Sep 17 00:00:00 2001
From: LB7666 <acking-you@foxmail.com>
Date: Fri, 26 Jun 2026 03:37:44 +0800
Subject: [PATCH 1/3] feat(llm-access): add standalone Codex image gateway

---
 Cargo.lock                                    |  21 +
 Cargo.toml                                    |   1 +
 crates/frontend/src/api.rs                    |  44 ++
 .../frontend/src/pages/admin_kiro_gateway.rs  |   2 +
 .../frontend/src/pages/admin_llm_gateway.rs   | 205 +++++
 crates/llm-access-codex-image/Cargo.toml      |  27 +
 crates/llm-access-codex-image/src/dispatch.rs |  54 ++
 crates/llm-access-codex-image/src/lib.rs      |  10 +
 crates/llm-access-codex-image/src/limiter.rs  |  61 ++
 crates/llm-access-codex-image/src/logging.rs  | 262 +++++++
 crates/llm-access-codex-image/src/main.rs     | 703 ++++++++++++++++++
 crates/llm-access-codex-image/src/request.rs  | 240 ++++++
 .../tests/codex_image_dispatch.rs             | 129 ++++
 .../tests/codex_image_request.rs              |  99 +++
 .../src/store/codex_account.rs                |  17 +
 crates/llm-access-core/src/store/empty.rs     |   6 +-
 crates/llm-access-core/src/store/keys.rs      |   5 +
 crates/llm-access-core/src/store/mod.rs       |   2 +
 crates/llm-access-core/src/store/routes.rs    |   6 +
 .../migrations/postgres/0001_init.sql         |   1 +
 .../0030_codex_image_generation_toggle.sql    |   2 +
 crates/llm-access-migrations/src/lib.rs       |   5 +
 crates/llm-access-store/src/duckdb.rs         |   1 +
 crates/llm-access-store/src/lib.rs            |   1 +
 crates/llm-access-store/src/postgres.rs       |  24 +
 crates/llm-access-store/src/postgres/cache.rs |   7 +
 .../src/postgres/codex_account.rs             |  71 ++
 .../llm-access-store/src/postgres/decode.rs   |  54 +-
 crates/llm-access-store/src/postgres/keys.rs  |  17 +-
 .../llm-access-store/src/postgres/routes.rs   |   8 +
 crates/llm-access-store/src/records.rs        |   2 +
 crates/llm-access-store/src/request_cache.rs  |  92 ++-
 crates/llm-access/src/admin.rs                |  37 +
 crates/llm-access/src/codex_refresh.rs        |   4 +
 crates/llm-access/src/codex_status.rs         |   3 +
 .../src/provider/route_selection.rs           |   3 +
 crates/llm-access/src/provider/tests.rs       |  16 +
 .../caddy/llm-access-path-split.Caddyfile     |  16 +
 .../llm-access-codex-image.service.template   |  33 +
 scripts/activate_llm_access_cloud_release.sh  |  68 +-
 scripts/prepare_llm_access_cloud_release.sh   |  25 +-
 ...lease_llm_access_cloud_codex_image_only.sh |  74 ++
 scripts/render_llm_access_cloud_bundle.sh     |   1 +
 scripts/test_llm_access_cloud_bundle.sh       |   6 +
 .../test_llm_access_cloud_release_scripts.sh  |  19 +-
 45 files changed, 2444 insertions(+), 40 deletions(-)
 create mode 100644 crates/llm-access-codex-image/Cargo.toml
 create mode 100644 crates/llm-access-codex-image/src/dispatch.rs
 create mode 100644 crates/llm-access-codex-image/src/lib.rs
 create mode 100644 crates/llm-access-codex-image/src/limiter.rs
 create mode 100644 crates/llm-access-codex-image/src/logging.rs
 create mode 100644 crates/llm-access-codex-image/src/main.rs
 create mode 100644 crates/llm-access-codex-image/src/request.rs
 create mode 100644 crates/llm-access-codex-image/tests/codex_image_dispatch.rs
 create mode 100644 crates/llm-access-codex-image/tests/codex_image_request.rs
 create mode 100644 crates/llm-access-migrations/migrations/postgres/0030_codex_image_generation_toggle.sql
 create mode 100644 deployment-examples/systemd/llm-access-codex-image.service.template
 create mode 100755 scripts/release_llm_access_cloud_codex_image_only.sh

diff --git a/Cargo.lock b/Cargo.lock
index ea297d72..d1efb78e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5745,6 +5745,27 @@ dependencies = [
  "zstd",
 ]
 
+[[package]]
+name = "llm-access-codex-image"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "axum",
+ "bytes",
+ "clap",
+ "llm-access-codex",
+ "llm-access-core",
+ "llm-access-store",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "sha2 0.10.9",
+ "tokio",
+ "tower 0.5.2",
+ "tracing",
+ "tracing-subscriber",
+]
+
 [[package]]
 name = "llm-access-core"
 version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 427b4062..a43b62ef 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -15,6 +15,7 @@ members = [
     "crates/llm-access",
     "crates/llm-access-core",
     "crates/llm-access-codex",
+    "crates/llm-access-codex-image",
     "crates/llm-access-kiro",
     "crates/llm-access-migrations",
     "crates/llm-access-store",
diff --git a/crates/frontend/src/api.rs b/crates/frontend/src/api.rs
index 27cfc4f5..0e358d45 100644
--- a/crates/frontend/src/api.rs
+++ b/crates/frontend/src/api.rs
@@ -6066,6 +6066,10 @@ const fn default_true() -> bool {
     true
 }
 
+const fn default_codex_image_generation_max_concurrency() -> u64 {
+    3
+}
+
 fn default_kiro_pool_strategy() -> String {
     llm_store::default_kiro_pool_strategy()
 }
@@ -6112,6 +6116,8 @@ pub struct AdminLlmGatewayKeyView {
     pub codex_fast_enabled: bool,
     #[serde(default)]
     pub codex_strict_session_rejection_enabled: bool,
+    #[serde(default)]
+    pub codex_image_generation_enabled: bool,
     #[serde(default = "default_true")]
     pub kiro_request_validation_enabled: bool,
     #[serde(default = "default_true")]
@@ -8985,6 +8991,7 @@ pub async fn create_admin_llm_gateway_key(
             uses_global_kiro_billable_model_multipliers: true,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: false,
             kiro_candidate_credit_summary: None,
         })
     }
@@ -9032,6 +9039,7 @@ pub struct PatchAdminLlmGatewayKeyRequest<'a> {
     pub request_min_start_interval_ms: Option<u64>,
     pub codex_fast_enabled: Option<bool>,
     pub codex_strict_session_rejection_enabled: Option<bool>,
+    pub codex_image_generation_enabled: Option<bool>,
     pub kiro_request_validation_enabled: Option<bool>,
     pub kiro_cache_estimation_enabled: Option<bool>,
     pub kiro_zero_cache_debug_enabled: Option<bool>,
@@ -9068,6 +9076,7 @@ pub async fn patch_admin_llm_gateway_key(
             request.request_min_start_interval_ms,
             request.codex_fast_enabled,
             request.codex_strict_session_rejection_enabled,
+            request.codex_image_generation_enabled,
             request.kiro_request_validation_enabled,
             request.kiro_cache_estimation_enabled,
             request.kiro_zero_cache_debug_enabled,
@@ -9179,6 +9188,12 @@ pub async fn patch_admin_llm_gateway_key(
                 serde_json::Value::Bool(enabled),
             );
         }
+        if let Some(enabled) = request.codex_image_generation_enabled {
+            body.insert(
+                "codex_image_generation_enabled".to_string(),
+                serde_json::Value::Bool(enabled),
+            );
+        }
         if let Some(kiro_request_validation_enabled) = request.kiro_request_validation_enabled {
             body.insert(
                 "kiro_request_validation_enabled".to_string(),
@@ -9855,6 +9870,10 @@ pub struct AccountSummaryView {
     pub auto_refresh_enabled: bool,
     pub request_max_concurrency: Option<u64>,
     pub request_min_start_interval_ms: Option<u64>,
+    #[serde(default)]
+    pub codex_image_generation_enabled: bool,
+    #[serde(default = "default_codex_image_generation_max_concurrency")]
+    pub codex_image_generation_max_concurrency: u64,
     pub proxy_mode: String,
     pub proxy_config_id: Option<String>,
     pub effective_proxy_source: String,
@@ -9883,6 +9902,9 @@ impl Default for AccountSummaryView {
             auto_refresh_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency: default_codex_image_generation_max_concurrency(
+            ),
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
@@ -10248,6 +10270,9 @@ pub async fn import_admin_llm_gateway_account(
             auto_refresh_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency: default_codex_image_generation_max_concurrency(
+            ),
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
@@ -10347,6 +10372,8 @@ pub struct PatchAdminLlmGatewayAccountInput {
     pub proxy_config_id: Option<String>,
     pub request_max_concurrency: Option<u64>,
     pub request_min_start_interval_ms: Option<u64>,
+    pub codex_image_generation_enabled: Option<bool>,
+    pub codex_image_generation_max_concurrency: Option<u64>,
     pub request_max_concurrency_unlimited: bool,
     pub request_min_start_interval_ms_unlimited: bool,
 }
@@ -10373,6 +10400,10 @@ pub async fn patch_admin_llm_gateway_account(
             auto_refresh_enabled: input.auto_refresh_enabled.unwrap_or(true),
             request_max_concurrency: input.request_max_concurrency,
             request_min_start_interval_ms: input.request_min_start_interval_ms,
+            codex_image_generation_enabled: input.codex_image_generation_enabled.unwrap_or(false),
+            codex_image_generation_max_concurrency: input
+                .codex_image_generation_max_concurrency
+                .unwrap_or_else(default_codex_image_generation_max_concurrency),
             proxy_mode: input
                 .proxy_mode
                 .clone()
@@ -10430,6 +10461,9 @@ pub async fn refresh_admin_llm_gateway_account(name: &str) -> Result<AccountSumm
             auto_refresh_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency: default_codex_image_generation_max_concurrency(
+            ),
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
@@ -10492,6 +10526,9 @@ pub async fn refresh_admin_llm_gateway_account_auth(
             auto_refresh_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency: default_codex_image_generation_max_concurrency(
+            ),
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
@@ -10563,6 +10600,9 @@ pub async fn consume_admin_llm_gateway_account_rate_limit_reset_credit(
                 auto_refresh_enabled: true,
                 request_max_concurrency: None,
                 request_min_start_interval_ms: None,
+                codex_image_generation_enabled: false,
+                codex_image_generation_max_concurrency:
+                    default_codex_image_generation_max_concurrency(),
                 proxy_mode: "inherit".to_string(),
                 proxy_config_id: None,
                 effective_proxy_source: "binding".to_string(),
@@ -11225,6 +11265,7 @@ pub async fn create_admin_kiro_key(
             uses_global_kiro_billable_model_multipliers: true,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: false,
             kiro_candidate_credit_summary: None,
         })
     }
@@ -11960,6 +12001,7 @@ mod tests {
 
         assert!(!key.kiro_full_request_logging_enabled);
         assert!(!key.kiro_remote_media_resolution_enabled);
+        assert!(!key.codex_image_generation_enabled);
     }
 
     #[test]
@@ -12084,6 +12126,8 @@ mod tests {
         .expect("account summary should parse");
 
         assert_eq!(account.rate_limit_reset_credits_available, Some(2));
+        assert!(!account.codex_image_generation_enabled);
+        assert_eq!(account.codex_image_generation_max_concurrency, 3);
     }
 
     #[test]
diff --git a/crates/frontend/src/pages/admin_kiro_gateway.rs b/crates/frontend/src/pages/admin_kiro_gateway.rs
index eee874cf..cc9743f4 100644
--- a/crates/frontend/src/pages/admin_kiro_gateway.rs
+++ b/crates/frontend/src/pages/admin_kiro_gateway.rs
@@ -1899,6 +1899,7 @@ fn kiro_key_editor_card(props: &KiroKeyEditorCardProps) -> Html {
                     request_min_start_interval_ms: None,
                     codex_fast_enabled: None,
                     codex_strict_session_rejection_enabled: None,
+                    codex_image_generation_enabled: None,
                     kiro_request_validation_enabled: Some(kiro_request_validation_enabled_value),
                     kiro_cache_estimation_enabled: Some(kiro_cache_estimation_enabled_value),
                     kiro_zero_cache_debug_enabled: Some(kiro_zero_cache_debug_enabled_value),
@@ -2006,6 +2007,7 @@ fn kiro_key_editor_card(props: &KiroKeyEditorCardProps) -> Html {
                     request_min_start_interval_ms: None,
                     codex_fast_enabled: None,
                     codex_strict_session_rejection_enabled: None,
+                    codex_image_generation_enabled: None,
                     kiro_request_validation_enabled: None,
                     kiro_cache_estimation_enabled: Some(kiro_cache_estimation_enabled_value),
                     kiro_zero_cache_debug_enabled: Some(kiro_zero_cache_debug_enabled_value),
diff --git a/crates/frontend/src/pages/admin_llm_gateway.rs b/crates/frontend/src/pages/admin_llm_gateway.rs
index 31a3503f..e91c33a7 100644
--- a/crates/frontend/src/pages/admin_llm_gateway.rs
+++ b/crates/frontend/src/pages/admin_llm_gateway.rs
@@ -90,6 +90,8 @@ const PROXY_TRAFFIC_QUERY_WINDOW_DAYS: u64 = 30;
 const ADMIN_CODEX_IMPORT_JOB_LIST_LIMIT: usize = 10;
 const ACCOUNT_PAGE_SIZE: usize = 8;
 const KEY_PAGE_SIZE: usize = 8;
+const CODEX_IMAGE_DEFAULT_CONCURRENCY: u64 = 3;
+const CODEX_IMAGE_MAX_CONCURRENCY: u64 = 1024;
 const ACCOUNT_ACCENT_BORDERS: &[&str] = &[
     "border-l-4 border-l-teal-500/70",
     "border-l-4 border-l-violet-500/70",
@@ -484,6 +486,28 @@ fn account_rate_limit_bucket<'a>(
         })
 }
 
+fn account_image_rate_limit_bucket<'a>(
+    status: Option<&'a LlmGatewayRateLimitStatusResponse>,
+    account_name: &str,
+) -> Option<&'a LlmGatewayRateLimitBucketView> {
+    let status = status?;
+    status.buckets.iter().find(|bucket| {
+        if bucket.account_name.as_deref() != Some(account_name) {
+            return false;
+        }
+        let limit_id = bucket.limit_id.to_ascii_lowercase();
+        let limit_name = bucket
+            .limit_name
+            .as_deref()
+            .unwrap_or_default()
+            .to_ascii_lowercase();
+        let display_name = bucket.display_name.to_ascii_lowercase();
+        [limit_id.as_str(), limit_name.as_str(), display_name.as_str()]
+            .iter()
+            .any(|value| value.contains("gpt-image") || value.contains("image"))
+    })
+}
+
 fn account_limit_remaining_percent(
     window: Option<&LlmGatewayRateLimitWindowView>,
     fallback: Option<f64>,
@@ -1245,6 +1269,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
     let codex_fast_enabled = use_state(|| key_item.codex_fast_enabled);
     let codex_strict_session_rejection_enabled =
         use_state(|| key_item.codex_strict_session_rejection_enabled);
+    let codex_image_generation_enabled = use_state(|| key_item.codex_image_generation_enabled);
     let saving = use_state(|| false);
     let feedback = use_state(|| None::<String>);
 
@@ -1262,6 +1287,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
         let request_min_start_interval_ms = request_min_start_interval_ms.clone();
         let codex_fast_enabled = codex_fast_enabled.clone();
         let codex_strict_session_rejection_enabled = codex_strict_session_rejection_enabled.clone();
+        let codex_image_generation_enabled = codex_image_generation_enabled.clone();
         use_effect_with((props.key_item.clone(), props.account_groups.clone()), move |_| {
             name.set(key_item.name.clone());
             quota.set(key_item.quota_billable_limit.to_string());
@@ -1293,6 +1319,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
             codex_fast_enabled.set(key_item.codex_fast_enabled);
             codex_strict_session_rejection_enabled
                 .set(key_item.codex_strict_session_rejection_enabled);
+            codex_image_generation_enabled.set(key_item.codex_image_generation_enabled);
             || ()
         });
     }
@@ -1361,6 +1388,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
         let request_min_start_interval_ms = request_min_start_interval_ms.clone();
         let codex_fast_enabled = codex_fast_enabled.clone();
         let codex_strict_session_rejection_enabled = codex_strict_session_rejection_enabled.clone();
+        let codex_image_generation_enabled = codex_image_generation_enabled.clone();
         let saving = saving.clone();
         let feedback = feedback.clone();
         let on_flash = props.on_flash.clone();
@@ -1381,6 +1409,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
             let codex_fast_enabled_value = *codex_fast_enabled;
             let codex_strict_session_rejection_enabled_value =
                 *codex_strict_session_rejection_enabled;
+            let codex_image_generation_enabled_value = *codex_image_generation_enabled;
             let saving = saving.clone();
             let feedback = feedback.clone();
             let on_flash = on_flash.clone();
@@ -1440,6 +1469,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
                     codex_strict_session_rejection_enabled: Some(
                         codex_strict_session_rejection_enabled_value,
                     ),
+                    codex_image_generation_enabled: Some(codex_image_generation_enabled_value),
                     kiro_request_validation_enabled: None,
                     kiro_cache_estimation_enabled: None,
                     kiro_zero_cache_debug_enabled: None,
@@ -1704,6 +1734,21 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
                     />
                     <span>{ "严格拒绝 fatal session" }</span>
                 </label>
+                <label class={classes!("flex", "items-center", "gap-2", "text-sm")}>
+                    <input
+                        type="checkbox"
+                        checked={*codex_image_generation_enabled}
+                        onchange={{
+                            let codex_image_generation_enabled = codex_image_generation_enabled.clone();
+                            Callback::from(move |event: Event| {
+                                if let Some(target) = event.target_dyn_into::<HtmlInputElement>() {
+                                    codex_image_generation_enabled.set(target.checked());
+                                }
+                            })
+                        }}
+                    />
+                    <span>{ "允许 gpt-image-2" }</span>
+                </label>
                 <select
                     key={format!("{}-status-{}", key_item.id, (*status).clone())}
                     class={classes!("rounded-lg", "border", "border-[var(--border)]", "bg-[var(--surface)]", "px-3", "py-1.5", "text-sm")}
@@ -1813,6 +1858,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
                     "间隔 {}ms",
                     key_item.request_min_start_interval_ms.map(|value| value.to_string()).unwrap_or_else(|| "∞".to_string())
                 ) }</span>
+                <span>{ if key_item.codex_image_generation_enabled { "生图 on" } else { "生图 off" } }</span>
                 <span>{ format!("Credit {}", key_credit_display(&key_item)) }</span>
                 if key_item.usage_credit_missing_events > 0 {
                     <span>{ format!("partial {}", key_item.usage_credit_missing_events) }</span>
@@ -2776,6 +2822,8 @@ pub fn admin_llm_gateway_page() -> Html {
     let account_route_weight_tier_inputs = use_state(BTreeMap::<String, String>::new);
     let account_request_max_inputs = use_state(BTreeMap::<String, String>::new);
     let account_request_min_inputs = use_state(BTreeMap::<String, String>::new);
+    let account_image_enabled_inputs = use_state(BTreeMap::<String, bool>::new);
+    let account_image_concurrency_inputs = use_state(BTreeMap::<String, String>::new);
     let show_import_form = use_state(|| false);
     let account_search = use_state(String::new);
     let account_active_query = use_state(String::new);
@@ -3120,6 +3168,8 @@ pub fn admin_llm_gateway_page() -> Html {
         let account_route_weight_tier_inputs = account_route_weight_tier_inputs.clone();
         let account_request_max_inputs = account_request_max_inputs.clone();
         let account_request_min_inputs = account_request_min_inputs.clone();
+        let account_image_enabled_inputs = account_image_enabled_inputs.clone();
+        let account_image_concurrency_inputs = account_image_concurrency_inputs.clone();
         let account_group_candidate_accounts = account_group_candidate_accounts.clone();
         let account_group_candidate_loading = account_group_candidate_loading.clone();
         let keys_search = keys_search.clone();
@@ -3199,6 +3249,8 @@ pub fn admin_llm_gateway_page() -> Html {
             let account_route_weight_tier_inputs = account_route_weight_tier_inputs.clone();
             let account_request_max_inputs = account_request_max_inputs.clone();
             let account_request_min_inputs = account_request_min_inputs.clone();
+            let account_image_enabled_inputs = account_image_enabled_inputs.clone();
+            let account_image_concurrency_inputs = account_image_concurrency_inputs.clone();
             let account_group_candidate_accounts = account_group_candidate_accounts.clone();
             let account_group_candidate_loading = account_group_candidate_loading.clone();
             let keys_search = keys_search.clone();
@@ -3514,6 +3566,23 @@ pub fn admin_llm_gateway_page() -> Html {
                                     )
                                 })
                                 .collect::<BTreeMap<_, _>>();
+                            let next_image_enabled_inputs = accounts_resp
+                                .accounts
+                                .iter()
+                                .map(|account| {
+                                    (account.name.clone(), account.codex_image_generation_enabled)
+                                })
+                                .collect::<BTreeMap<_, _>>();
+                            let next_image_concurrency_inputs = accounts_resp
+                                .accounts
+                                .iter()
+                                .map(|account| {
+                                    (
+                                        account.name.clone(),
+                                        account.codex_image_generation_max_concurrency.to_string(),
+                                    )
+                                })
+                                .collect::<BTreeMap<_, _>>();
                             accounts_total.set(accounts_resp.total);
                             account_page_limit.set(accounts_resp.limit.max(1));
                             accounts.set(accounts_resp.accounts);
@@ -3521,6 +3590,8 @@ pub fn admin_llm_gateway_page() -> Html {
                             account_route_weight_tier_inputs.set(next_route_weight_tier_inputs);
                             account_request_max_inputs.set(next_request_max_inputs);
                             account_request_min_inputs.set(next_request_min_inputs);
+                            account_image_enabled_inputs.set(next_image_enabled_inputs);
+                            account_image_concurrency_inputs.set(next_image_concurrency_inputs);
                             codex_rate_limit_status.set(codex_status_resp);
                         } else if active_tab_value != TAB_GROUPS {
                             accounts_total.set(0);
@@ -3530,6 +3601,8 @@ pub fn admin_llm_gateway_page() -> Html {
                             account_route_weight_tier_inputs.set(BTreeMap::new());
                             account_request_max_inputs.set(BTreeMap::new());
                             account_request_min_inputs.set(BTreeMap::new());
+                            account_image_enabled_inputs.set(BTreeMap::new());
+                            account_image_concurrency_inputs.set(BTreeMap::new());
                         }
                         if active_tab_value != TAB_GROUPS {
                             account_group_candidate_accounts.set(Vec::new());
@@ -4970,6 +5043,8 @@ pub fn admin_llm_gateway_page() -> Html {
                         proxy_config_id: None,
                         request_max_concurrency: None,
                         request_min_start_interval_ms: None,
+                        codex_image_generation_enabled: None,
+                        codex_image_generation_max_concurrency: None,
                         request_max_concurrency_unlimited: false,
                         request_min_start_interval_ms_unlimited: false,
                     },
@@ -5019,6 +5094,8 @@ pub fn admin_llm_gateway_page() -> Html {
                         proxy_config_id: None,
                         request_max_concurrency: None,
                         request_min_start_interval_ms: None,
+                        codex_image_generation_enabled: None,
+                        codex_image_generation_max_concurrency: None,
                         request_max_concurrency_unlimited: false,
                         request_min_start_interval_ms_unlimited: false,
                     },
@@ -5068,6 +5145,8 @@ pub fn admin_llm_gateway_page() -> Html {
                         proxy_config_id: None,
                         request_max_concurrency: None,
                         request_min_start_interval_ms: None,
+                        codex_image_generation_enabled: None,
+                        codex_image_generation_max_concurrency: None,
                         request_max_concurrency_unlimited: false,
                         request_min_start_interval_ms_unlimited: false,
                     },
@@ -5099,6 +5178,8 @@ pub fn admin_llm_gateway_page() -> Html {
         let account_route_weight_tier_inputs = account_route_weight_tier_inputs.clone();
         let account_request_max_inputs = account_request_max_inputs.clone();
         let account_request_min_inputs = account_request_min_inputs.clone();
+        let account_image_enabled_inputs = account_image_enabled_inputs.clone();
+        let account_image_concurrency_inputs = account_image_concurrency_inputs.clone();
         let accounts = accounts.clone();
         let load_error = load_error.clone();
         Callback::from(move |account_name: String| {
@@ -5107,9 +5188,15 @@ pub fn admin_llm_gateway_page() -> Html {
             let account_route_weight_tier_inputs = account_route_weight_tier_inputs.clone();
             let account_request_max_inputs = account_request_max_inputs.clone();
             let account_request_min_inputs = account_request_min_inputs.clone();
+            let account_image_enabled_inputs = account_image_enabled_inputs.clone();
+            let account_image_concurrency_inputs = account_image_concurrency_inputs.clone();
             let accounts = accounts.clone();
             let load_error = load_error.clone();
             wasm_bindgen_futures::spawn_local(async move {
+                let current_account = (*accounts)
+                    .iter()
+                    .find(|account| account.name == account_name)
+                    .cloned();
                 let selection = (*account_proxy_inputs)
                     .get(&account_name)
                     .cloned()
@@ -5126,6 +5213,24 @@ pub fn admin_llm_gateway_page() -> Html {
                     .get(&account_name)
                     .cloned()
                     .unwrap_or_default();
+                let image_enabled = (*account_image_enabled_inputs)
+                    .get(&account_name)
+                    .copied()
+                    .or_else(|| {
+                        current_account
+                            .as_ref()
+                            .map(|account| account.codex_image_generation_enabled)
+                    })
+                    .unwrap_or(false);
+                let image_concurrency_raw = (*account_image_concurrency_inputs)
+                    .get(&account_name)
+                    .cloned()
+                    .or_else(|| {
+                        current_account.as_ref().map(|account| {
+                            account.codex_image_generation_max_concurrency.to_string()
+                        })
+                    })
+                    .unwrap_or_else(|| CODEX_IMAGE_DEFAULT_CONCURRENCY.to_string());
                 let (proxy_mode, proxy_config_id) = if selection == "direct" {
                     (Some("direct".to_string()), None)
                 } else if let Some(proxy_config_id) = selection.strip_prefix("fixed:") {
@@ -5158,6 +5263,22 @@ pub fn admin_llm_gateway_page() -> Html {
                         },
                     }
                 };
+                let codex_image_generation_max_concurrency = if image_concurrency_raw
+                    .trim()
+                    .is_empty()
+                {
+                    CODEX_IMAGE_DEFAULT_CONCURRENCY
+                } else {
+                    match image_concurrency_raw.trim().parse::<u64>() {
+                        Ok(value) if (1..=CODEX_IMAGE_MAX_CONCURRENCY).contains(&value) => value,
+                        _ => {
+                            load_error.set(Some(format!(
+                                "生图并发必须是 1..={CODEX_IMAGE_MAX_CONCURRENCY} 的整数"
+                            )));
+                            return;
+                        },
+                    }
+                };
 
                 let mut inflight = (*account_action_inflight).clone();
                 inflight.insert(account_name.clone());
@@ -5174,6 +5295,10 @@ pub fn admin_llm_gateway_page() -> Html {
                         proxy_config_id,
                         request_max_concurrency,
                         request_min_start_interval_ms,
+                        codex_image_generation_enabled: Some(image_enabled),
+                        codex_image_generation_max_concurrency: Some(
+                            codex_image_generation_max_concurrency,
+                        ),
                         request_max_concurrency_unlimited: request_max_concurrency.is_none(),
                         request_min_start_interval_ms_unlimited: request_min_start_interval_ms
                             .is_none(),
@@ -5216,6 +5341,17 @@ pub fn admin_llm_gateway_page() -> Html {
                                 .unwrap_or_default(),
                         );
                         account_request_min_inputs.set(next_request_min_inputs);
+                        let mut next_image_enabled_inputs = (*account_image_enabled_inputs).clone();
+                        next_image_enabled_inputs
+                            .insert(updated.name.clone(), updated.codex_image_generation_enabled);
+                        account_image_enabled_inputs.set(next_image_enabled_inputs);
+                        let mut next_image_concurrency_inputs =
+                            (*account_image_concurrency_inputs).clone();
+                        next_image_concurrency_inputs.insert(
+                            updated.name.clone(),
+                            updated.codex_image_generation_max_concurrency.to_string(),
+                        );
+                        account_image_concurrency_inputs.set(next_image_concurrency_inputs);
                         load_error.set(None);
                     },
                     Err(err) => load_error.set(Some(err)),
@@ -8891,6 +9027,8 @@ pub fn admin_llm_gateway_page() -> Html {
                                 let acc_name_for_settings_save = acc.name.clone();
                                 let acc_name_for_request_max_change = acc.name.clone();
                                 let acc_name_for_request_min_change = acc.name.clone();
+                                let acc_name_for_image_enabled_change = acc.name.clone();
+                                let acc_name_for_image_concurrency_change = acc.name.clone();
                                 let acc_name = acc.name.clone();
                                 let acc_status = acc.status.clone();
                                 let account_disabled = acc_status == "disabled";
@@ -8933,6 +9071,17 @@ pub fn admin_llm_gateway_page() -> Html {
                                             .map(|value| value.to_string())
                                             .unwrap_or_default()
                                     });
+                                let selected_image_enabled = (*account_image_enabled_inputs)
+                                    .get(&acc_name)
+                                    .copied()
+                                    .unwrap_or(acc.codex_image_generation_enabled);
+                                let selected_image_concurrency_value =
+                                    (*account_image_concurrency_inputs)
+                                        .get(&acc_name)
+                                        .cloned()
+                                        .unwrap_or_else(|| {
+                                            acc.codex_image_generation_max_concurrency.to_string()
+                                        });
                                 let configured_proxy_line = account_configured_proxy_label(acc);
                                 let effective_proxy_line = format!(
                                     "effective: {} · {}",
@@ -8948,6 +9097,26 @@ pub fn admin_llm_gateway_page() -> Html {
                                         .map(|value| format!("{} ms", value))
                                         .unwrap_or_else(|| "∞".to_string())
                                 );
+                                let image_rate_limit_bucket = account_image_rate_limit_bucket(
+                                    (*codex_rate_limit_status).as_ref(),
+                                    &acc_name,
+                                );
+                                let image_quota_line = if acc.codex_image_generation_enabled {
+                                    if let Some(bucket) = image_rate_limit_bucket {
+                                        format!(
+                                            "image on · concurrency {} · bucket {}",
+                                            acc.codex_image_generation_max_concurrency,
+                                            bucket.display_name
+                                        )
+                                    } else {
+                                        format!(
+                                            "image on · concurrency {} · common Codex quota",
+                                            acc.codex_image_generation_max_concurrency
+                                        )
+                                    }
+                                } else {
+                                    "image off · common Codex quota".to_string()
+                                };
                                 let last_refresh_line = acc
                                     .last_refresh
                                     .map(format_ms)
@@ -9084,6 +9253,7 @@ pub fn admin_llm_gateway_page() -> Html {
                                                     }
                                                 </div>
                                                 <div>{ scheduler_line.clone() }</div>
+                                                <div>{ image_quota_line.clone() }</div>
                                                 <div>{ format!("route weight tier: {}", acc.route_weight_tier) }</div>
                                                 <div>{ format!("reset credits available: {}", reset_credits_label) }</div>
                                                 <div class={classes!("flex", "gap-3", "flex-wrap")}>
@@ -9187,6 +9357,41 @@ pub fn admin_llm_gateway_page() -> Html {
                                                     <option value="pro5x" selected={selected_route_weight_tier == "pro5x"}>{ "Pro5x" }</option>
                                                     <option value="pro20x" selected={selected_route_weight_tier == "pro20x"}>{ "Pro20x" }</option>
                                                 </select>
+                                                <label class={classes!("inline-flex", "items-center", "gap-1.5", "rounded-lg", "border", "border-[var(--border)]", "bg-[var(--surface)]", "px-2", "py-1.5", "text-xs")}>
+                                                    <input
+                                                        type="checkbox"
+                                                        checked={selected_image_enabled}
+                                                        onchange={{
+                                                            let account_image_enabled_inputs = account_image_enabled_inputs.clone();
+                                                            Callback::from(move |event: Event| {
+                                                                if let Some(target) = event.target_dyn_into::<HtmlInputElement>() {
+                                                                    let mut next = (*account_image_enabled_inputs).clone();
+                                                                    next.insert(acc_name_for_image_enabled_change.clone(), target.checked());
+                                                                    account_image_enabled_inputs.set(next);
+                                                                }
+                                                            })
+                                                        }}
+                                                    />
+                                                    <span>{ "生图" }</span>
+                                                </label>
+                                                <input
+                                                    type="number"
+                                                    min="1"
+                                                    max={CODEX_IMAGE_MAX_CONCURRENCY.to_string()}
+                                                    class={classes!("w-24", "rounded-lg", "border", "border-[var(--border)]", "bg-[var(--surface)]", "px-2", "py-1.5", "text-xs")}
+                                                    placeholder="生图并发"
+                                                    value={selected_image_concurrency_value.clone()}
+                                                    oninput={{
+                                                        let account_image_concurrency_inputs = account_image_concurrency_inputs.clone();
+                                                        Callback::from(move |event: InputEvent| {
+                                                            if let Some(target) = event.target_dyn_into::<HtmlInputElement>() {
+                                                                let mut next = (*account_image_concurrency_inputs).clone();
+                                                                next.insert(acc_name_for_image_concurrency_change.clone(), target.value());
+                                                                account_image_concurrency_inputs.set(next);
+                                                            }
+                                                        })
+                                                    }}
+                                                />
                                                 <button
                                                     class={classes!("btn-terminal")}
                                                     onclick={Callback::from(move |_| on_save_account_settings.emit(acc_name_for_settings_save.clone()))}
diff --git a/crates/llm-access-codex-image/Cargo.toml b/crates/llm-access-codex-image/Cargo.toml
new file mode 100644
index 00000000..bd77ced7
--- /dev/null
+++ b/crates/llm-access-codex-image/Cargo.toml
@@ -0,0 +1,27 @@
+[package]
+name = "llm-access-codex-image"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lints]
+workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+axum = { workspace = true }
+bytes = { workspace = true }
+clap = { workspace = true }
+llm-access-codex = { path = "../llm-access-codex" }
+llm-access-core = { path = "../llm-access-core" }
+llm-access-store = { path = "../llm-access-store", default-features = false }
+reqwest = { workspace = true, features = ["json"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+[dev-dependencies]
+tower = { version = "0.5", features = ["util"] }
diff --git a/crates/llm-access-codex-image/src/dispatch.rs b/crates/llm-access-codex-image/src/dispatch.rs
new file mode 100644
index 00000000..2e086ca2
--- /dev/null
+++ b/crates/llm-access-codex-image/src/dispatch.rs
@@ -0,0 +1,54 @@
+use axum::http::StatusCode;
+use llm_access_core::store::ProviderCodexRoute;
+
+/// Error produced before attempting any upstream image request.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageDispatchError {
+    /// HTTP status to return to the downstream caller.
+    pub status: StatusCode,
+    /// Human-readable error message.
+    pub message: String,
+}
+
+impl ImageDispatchError {
+    fn new(status: StatusCode, message: impl Into<String>) -> Self {
+        Self {
+            status,
+            message: message.into(),
+        }
+    }
+}
+
+/// Filters resolved Codex routes to accounts allowed to serve image requests.
+pub fn eligible_image_routes(
+    routes: Vec<ProviderCodexRoute>,
+) -> Result<Vec<ProviderCodexRoute>, ImageDispatchError> {
+    if routes
+        .iter()
+        .any(|route| !route.codex_image_generation_enabled)
+    {
+        return Err(ImageDispatchError::new(
+            StatusCode::FORBIDDEN,
+            "codex image generation is disabled for this key",
+        ));
+    }
+    let routes = routes
+        .into_iter()
+        .filter(|route| route.account_codex_image_generation_enabled)
+        .collect::<Vec<_>>();
+    if routes.is_empty() {
+        return Err(ImageDispatchError::new(
+            StatusCode::SERVICE_UNAVAILABLE,
+            "no codex image-enabled accounts are available",
+        ));
+    }
+    Ok(routes)
+}
+
+/// Classifies upstream statuses that may be retried on another account.
+pub fn should_failover_status(status: StatusCode) -> bool {
+    status == StatusCode::UNAUTHORIZED
+        || status == StatusCode::FORBIDDEN
+        || status == StatusCode::TOO_MANY_REQUESTS
+        || status.is_server_error()
+}
diff --git a/crates/llm-access-codex-image/src/lib.rs b/crates/llm-access-codex-image/src/lib.rs
new file mode 100644
index 00000000..7ffd58c8
--- /dev/null
+++ b/crates/llm-access-codex-image/src/lib.rs
@@ -0,0 +1,10 @@
+//! Standalone Codex image gateway.
+
+/// Image-route eligibility and failover classification.
+pub mod dispatch;
+/// Independent per-account image concurrency limiter.
+pub mod limiter;
+/// Structured request log event construction.
+pub mod logging;
+/// JSON request validation and path normalization for the public image API.
+pub mod request;
diff --git a/crates/llm-access-codex-image/src/limiter.rs b/crates/llm-access-codex-image/src/limiter.rs
new file mode 100644
index 00000000..9abd821a
--- /dev/null
+++ b/crates/llm-access-codex-image/src/limiter.rs
@@ -0,0 +1,61 @@
+use std::{
+    collections::HashMap,
+    sync::{Arc, Mutex},
+};
+
+use llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY;
+
+/// Process-local limiter for Codex image requests.
+#[derive(Clone, Debug, Default)]
+pub struct ImageAccountLimiter {
+    states: Arc<Mutex<HashMap<String, u64>>>,
+}
+
+/// Permit held for the lifetime of one upstream image request.
+#[derive(Debug)]
+pub struct ImageAccountPermit {
+    scope: String,
+    states: Arc<Mutex<HashMap<String, u64>>>,
+}
+
+/// Returns the independent limiter scope used for image account concurrency.
+pub fn image_account_limiter_scope(account_name: &str) -> String {
+    format!("account:codex-image:{account_name}")
+}
+
+impl ImageAccountLimiter {
+    /// Attempts to acquire one account image permit without waiting.
+    pub fn try_acquire(
+        &self,
+        account_name: &str,
+        limit: Option<u64>,
+    ) -> Option<ImageAccountPermit> {
+        let limit = limit
+            .unwrap_or(DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY)
+            .max(1);
+        let scope = image_account_limiter_scope(account_name);
+        let mut states = self.states.lock().expect("image limiter mutex poisoned");
+        let in_flight = states.entry(scope.clone()).or_default();
+        if *in_flight >= limit {
+            return None;
+        }
+        *in_flight += 1;
+        Some(ImageAccountPermit {
+            scope,
+            states: Arc::clone(&self.states),
+        })
+    }
+}
+
+impl Drop for ImageAccountPermit {
+    fn drop(&mut self) {
+        let mut states = self.states.lock().expect("image limiter mutex poisoned");
+        let Some(in_flight) = states.get_mut(&self.scope) else {
+            return;
+        };
+        *in_flight = in_flight.saturating_sub(1);
+        if *in_flight == 0 {
+            states.remove(&self.scope);
+        }
+    }
+}
diff --git a/crates/llm-access-codex-image/src/logging.rs b/crates/llm-access-codex-image/src/logging.rs
new file mode 100644
index 00000000..725b6dbf
--- /dev/null
+++ b/crates/llm-access-codex-image/src/logging.rs
@@ -0,0 +1,262 @@
+use std::{
+    fs::{self, OpenOptions},
+    io::{BufWriter, Write},
+    path::PathBuf,
+    time::{SystemTime, UNIX_EPOCH},
+};
+
+use anyhow::Context;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+/// Upstream outcome fields recorded in the image request log.
+#[derive(Debug, Clone, Copy)]
+pub struct UpstreamLogInput<'a> {
+    /// Upstream HTTP status code, when a response was received.
+    pub status: Option<u16>,
+    /// Request duration in milliseconds.
+    pub duration_ms: u64,
+    /// Number of account failovers before the final outcome.
+    pub failover_count: u64,
+    /// Stable error class, when the request failed.
+    pub error_class: Option<&'a str>,
+    /// Number of images returned by upstream.
+    pub response_image_count: Option<u64>,
+    /// Total returned image payload bytes after decoding known response fields.
+    pub response_image_bytes: Option<u64>,
+    /// Usage token count if upstream exposed it.
+    pub usage_tokens: Option<u64>,
+    /// Whether usage metadata was absent.
+    pub usage_missing: bool,
+}
+
+/// Input used to build a redacted image request log event.
+#[derive(Debug, Clone, Copy)]
+pub struct ImageLogInput<'a> {
+    /// Stable request id for correlating logs.
+    pub request_id: &'a str,
+    /// Authenticated key id.
+    pub key_id: &'a str,
+    /// Authenticated key name.
+    pub key_name: &'a str,
+    /// Selected Codex account name.
+    pub account_name: Option<&'a str>,
+    /// Normalized endpoint name.
+    pub endpoint: &'a str,
+    /// Raw prompt, hashed but not stored.
+    pub prompt: &'a str,
+    /// Requested image size.
+    pub size: Option<&'a str>,
+    /// Requested image quality.
+    pub quality: Option<&'a str>,
+    /// Requested image count.
+    pub n: u64,
+    /// Edit input image sources, counted but not stored.
+    pub input_images: &'a [&'a str],
+    /// Upstream outcome.
+    pub upstream: UpstreamLogInput<'a>,
+}
+
+/// Redacted structured image request log event.
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ImageLogEvent {
+    /// Schema version for future log readers.
+    pub schema_version: u64,
+    /// Stable request id for correlating logs.
+    pub request_id: String,
+    /// Authenticated key id.
+    pub key_id: String,
+    /// Authenticated key name.
+    pub key_name: String,
+    /// Selected Codex account name.
+    pub account_name: Option<String>,
+    /// Normalized endpoint name.
+    pub endpoint: String,
+    /// SHA-256 hash of the prompt.
+    pub prompt_hash: String,
+    /// Requested image size.
+    pub size: Option<String>,
+    /// Requested image quality.
+    pub quality: Option<String>,
+    /// Requested image count.
+    pub n: u64,
+    /// Number of edit input images.
+    pub input_image_count: u64,
+    /// Number of data-url edit input images.
+    pub input_data_image_count: u64,
+    /// Upstream HTTP status code, when available.
+    pub upstream_status: Option<u16>,
+    /// Request duration in milliseconds.
+    pub duration_ms: u64,
+    /// Number of account failovers before the final outcome.
+    pub failover_count: u64,
+    /// Stable error class, when the request failed.
+    pub error_class: Option<String>,
+    /// Number of images returned by upstream.
+    pub response_image_count: Option<u64>,
+    /// Total returned image payload bytes after decoding known response fields.
+    pub response_image_bytes: Option<u64>,
+    /// Usage token count if upstream exposed it.
+    pub usage_tokens: Option<u64>,
+    /// Whether usage metadata was absent.
+    pub usage_missing: bool,
+}
+
+/// Runtime configuration for the image JSONL log writer.
+#[derive(Debug, Clone)]
+pub struct ImageLogConfig {
+    /// Directory containing active and sealed log files.
+    pub log_dir: PathBuf,
+    /// Maximum active file bytes before rollover.
+    pub max_file_bytes: u64,
+    /// Maximum active file age before rollover.
+    pub max_file_age_ms: u64,
+    /// Maximum sealed files retained.
+    pub max_files: usize,
+}
+
+/// Process-local JSONL image log writer.
+#[derive(Debug)]
+pub struct ImageLogWriter {
+    config: ImageLogConfig,
+    active_started_at_ms: u64,
+}
+
+impl ImageLogWriter {
+    /// Creates a writer and ensures the log directory exists.
+    pub fn new(config: ImageLogConfig) -> anyhow::Result<Self> {
+        fs::create_dir_all(&config.log_dir).with_context(|| {
+            format!("create codex image log directory `{}`", config.log_dir.display())
+        })?;
+        Ok(Self {
+            config,
+            active_started_at_ms: now_ms(),
+        })
+    }
+
+    /// Appends one redacted event as a JSON line.
+    pub fn append(&mut self, event: &ImageLogEvent) -> anyhow::Result<()> {
+        self.rotate_if_needed()?;
+        let active_path = self.active_path();
+        let file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&active_path)
+            .with_context(|| format!("open codex image log `{}`", active_path.display()))?;
+        let mut writer = BufWriter::new(file);
+        serde_json::to_writer(&mut writer, event).context("serialize codex image log event")?;
+        writer
+            .write_all(b"\n")
+            .context("write codex image log newline")?;
+        writer.flush().context("flush codex image log event")?;
+        Ok(())
+    }
+
+    fn rotate_if_needed(&mut self) -> anyhow::Result<()> {
+        let active_path = self.active_path();
+        let size_exceeded = active_path
+            .metadata()
+            .map(|metadata| metadata.len() >= self.config.max_file_bytes.max(1))
+            .unwrap_or(false);
+        let age_exceeded = now_ms().saturating_sub(self.active_started_at_ms)
+            >= self.config.max_file_age_ms.max(1);
+        if !size_exceeded && !age_exceeded {
+            return Ok(());
+        }
+        if active_path.exists() {
+            let sealed_path = self
+                .config
+                .log_dir
+                .join(format!("codex-image-{}.jsonl", now_ms()));
+            fs::rename(&active_path, &sealed_path).with_context(|| {
+                format!(
+                    "rotate codex image log `{}` to `{}`",
+                    active_path.display(),
+                    sealed_path.display()
+                )
+            })?;
+        }
+        self.active_started_at_ms = now_ms();
+        self.prune_sealed_logs()
+    }
+
+    fn prune_sealed_logs(&self) -> anyhow::Result<()> {
+        let mut files = fs::read_dir(&self.config.log_dir)
+            .with_context(|| {
+                format!("read codex image log dir `{}`", self.config.log_dir.display())
+            })?
+            .filter_map(Result::ok)
+            .filter_map(|entry| {
+                let file_name = entry.file_name();
+                let file_name = file_name.to_str()?;
+                if file_name.starts_with("codex-image-")
+                    && file_name.ends_with(".jsonl")
+                    && file_name != "codex-image-active.jsonl"
+                {
+                    Some(entry)
+                } else {
+                    None
+                }
+            })
+            .collect::<Vec<_>>();
+        if files.len() <= self.config.max_files {
+            return Ok(());
+        }
+        files.sort_by_key(|entry| {
+            entry
+                .metadata()
+                .and_then(|metadata| metadata.modified())
+                .unwrap_or(UNIX_EPOCH)
+        });
+        for entry in files.iter().take(files.len() - self.config.max_files) {
+            let _ = fs::remove_file(entry.path());
+        }
+        Ok(())
+    }
+
+    fn active_path(&self) -> PathBuf {
+        self.config.log_dir.join("codex-image-active.jsonl")
+    }
+}
+
+/// Builds a redacted log event that never stores raw prompts or base64 images.
+pub fn build_image_log_event(input: ImageLogInput<'_>) -> ImageLogEvent {
+    ImageLogEvent {
+        schema_version: 1,
+        request_id: input.request_id.to_string(),
+        key_id: input.key_id.to_string(),
+        key_name: input.key_name.to_string(),
+        account_name: input.account_name.map(ToString::to_string),
+        endpoint: input.endpoint.to_string(),
+        prompt_hash: prompt_hash(input.prompt),
+        size: input.size.map(ToString::to_string),
+        quality: input.quality.map(ToString::to_string),
+        n: input.n,
+        input_image_count: input.input_images.len() as u64,
+        input_data_image_count: input
+            .input_images
+            .iter()
+            .filter(|source| source.to_ascii_lowercase().starts_with("data:image/"))
+            .count() as u64,
+        upstream_status: input.upstream.status,
+        duration_ms: input.upstream.duration_ms,
+        failover_count: input.upstream.failover_count,
+        error_class: input.upstream.error_class.map(ToString::to_string),
+        response_image_count: input.upstream.response_image_count,
+        response_image_bytes: input.upstream.response_image_bytes,
+        usage_tokens: input.upstream.usage_tokens,
+        usage_missing: input.upstream.usage_missing,
+    }
+}
+
+fn prompt_hash(prompt: &str) -> String {
+    let digest = Sha256::digest(prompt.as_bytes());
+    digest.iter().map(|byte| format!("{byte:02x}")).collect()
+}
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis() as u64)
+        .unwrap_or(0)
+}
diff --git a/crates/llm-access-codex-image/src/main.rs b/crates/llm-access-codex-image/src/main.rs
new file mode 100644
index 00000000..89a74bff
--- /dev/null
+++ b/crates/llm-access-codex-image/src/main.rs
@@ -0,0 +1,703 @@
+//! Standalone Codex image gateway executable.
+
+use std::{
+    net::SocketAddr,
+    path::PathBuf,
+    sync::{Arc, Mutex},
+    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
+};
+
+use anyhow::{anyhow, Context};
+use axum::{
+    body::{to_bytes, Body, Bytes},
+    extract::State,
+    http::{header, HeaderMap, Method, Request, Response, StatusCode},
+    response::IntoResponse,
+    routing::get,
+    Router,
+};
+use clap::{Parser, Subcommand};
+use llm_access_codex_image::{
+    dispatch::{eligible_image_routes, should_failover_status},
+    limiter::ImageAccountLimiter,
+    logging::{
+        build_image_log_event, ImageLogConfig, ImageLogInput, ImageLogWriter, UpstreamLogInput,
+    },
+    request::{normalize_image_gateway_path, parse_image_request, upstream_image_path},
+};
+use llm_access_core::{
+    provider::{ProtocolFamily, ProviderType},
+    store::{
+        codex_auth_access_token_expires_at_ms, AdminConfigStore, AuthenticatedKey, ControlStore,
+        ProviderCodexRoute, ProviderProxyConfig, ProviderRouteStore, DEFAULT_CODEX_CLIENT_VERSION,
+        KEY_STATUS_ACTIVE,
+    },
+};
+use llm_access_store::{postgres::PostgresControlRepository, request_cache::RequestCacheConfig};
+use serde_json::Value;
+use tokio::net::TcpListener;
+
+const DEFAULT_BIND_ADDR: &str = "127.0.0.1:19082";
+const DEFAULT_CONTROL_DATABASE_URL_ENV: &str = "LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL";
+const DEFAULT_REQUEST_CACHE_URL_ENV: &str = "LLM_ACCESS_REQUEST_CACHE_URL";
+const DEFAULT_REQUEST_CACHE_KEY_PREFIX: &str = "llma";
+const DEFAULT_UPSTREAM_BASE_URL: &str = "https://chatgpt.com/backend-api/codex";
+const MAX_IMAGE_REQUEST_BODY_BYTES: usize = 24 * 1024 * 1024;
+
+#[derive(Debug, Parser)]
+#[command(name = "llm-access-codex-image")]
+struct Cli {
+    #[command(subcommand)]
+    command: Command,
+}
+
+#[derive(Debug, Subcommand)]
+enum Command {
+    Serve(ServeArgs),
+}
+
+#[derive(Debug, Parser)]
+struct ServeArgs {
+    #[arg(long, default_value = DEFAULT_BIND_ADDR)]
+    bind: SocketAddr,
+    #[arg(long)]
+    state_root: PathBuf,
+    #[arg(long, default_value = DEFAULT_CONTROL_DATABASE_URL_ENV)]
+    postgres_control_database_url_env: String,
+    #[arg(long, default_value = DEFAULT_REQUEST_CACHE_URL_ENV)]
+    request_cache_url_env: String,
+    #[arg(long, default_value = DEFAULT_REQUEST_CACHE_KEY_PREFIX)]
+    request_cache_key_prefix: String,
+    #[arg(long)]
+    image_log_dir: Option<PathBuf>,
+}
+
+#[derive(Clone)]
+struct AppState {
+    control: Arc<PostgresControlRepository>,
+    limiter: Arc<ImageAccountLimiter>,
+    image_log: Arc<Mutex<ImageLogWriter>>,
+    upstream_base: String,
+    codex_client_version: String,
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let _ = tracing_subscriber::fmt()
+        .with_env_filter(std::env::var("RUST_LOG").unwrap_or_else(|_| {
+            "warn,llm_access_codex_image=info,llm_access_store=info".to_string()
+        }))
+        .try_init();
+    match Cli::parse().command {
+        Command::Serve(args) => serve(args).await,
+    }
+}
+
+async fn serve(args: ServeArgs) -> anyhow::Result<()> {
+    let database_url =
+        std::env::var(&args.postgres_control_database_url_env).with_context(|| {
+            format!("missing control database env `{}`", args.postgres_control_database_url_env)
+        })?;
+    let request_cache_config = request_cache_config(&args)?;
+    let control = Arc::new(
+        PostgresControlRepository::connect_read_only(&database_url, request_cache_config)
+            .await
+            .context("connect read-only postgres control repository")?,
+    );
+    let runtime_config = control
+        .get_admin_runtime_config()
+        .await
+        .context("load runtime config")?;
+    let image_log_dir = args
+        .image_log_dir
+        .unwrap_or_else(|| args.state_root.join("codex-image-logs"));
+    let image_log = ImageLogWriter::new(ImageLogConfig {
+        log_dir: image_log_dir,
+        max_file_bytes: runtime_config.usage_journal_max_file_bytes,
+        max_file_age_ms: runtime_config.usage_journal_max_file_age_ms,
+        max_files: usize::try_from(runtime_config.usage_journal_max_files.max(1))
+            .unwrap_or(usize::MAX),
+    })?;
+    let state = Arc::new(AppState {
+        control,
+        limiter: Arc::new(ImageAccountLimiter::default()),
+        image_log: Arc::new(Mutex::new(image_log)),
+        upstream_base: codex_upstream_base_url(),
+        codex_client_version: normalize_codex_client_version(&runtime_config.codex_client_version)
+            .unwrap_or_else(|| DEFAULT_CODEX_CLIENT_VERSION.to_string()),
+    });
+    let app = Router::new()
+        .route("/healthz", get(|| async { "ok" }))
+        .fallback(handle_image_request)
+        .with_state(state);
+    let listener = TcpListener::bind(args.bind)
+        .await
+        .with_context(|| format!("bind codex image gateway on {}", args.bind))?;
+    tracing::info!(bind = %args.bind, "codex image gateway listening");
+    axum::serve(listener, app)
+        .await
+        .context("serve codex image gateway")
+}
+
+fn request_cache_config(args: &ServeArgs) -> anyhow::Result<Option<RequestCacheConfig>> {
+    let Some(url) = std::env::var(&args.request_cache_url_env)
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+    else {
+        return Ok(None);
+    };
+    let key_prefix = args.request_cache_key_prefix.trim();
+    if key_prefix.is_empty() {
+        return Err(anyhow!("--request-cache-key-prefix cannot be empty"));
+    }
+    Ok(Some(RequestCacheConfig {
+        url,
+        key_prefix: key_prefix.to_string(),
+    }))
+}
+
+async fn handle_image_request(
+    State(state): State<Arc<AppState>>,
+    request: Request<Body>,
+) -> axum::response::Response {
+    let request_id = new_request_id();
+    let started = Instant::now();
+    let path = request.uri().path().to_string();
+    let Some(endpoint) = normalize_image_gateway_path(&path) else {
+        return (StatusCode::NOT_FOUND, "unsupported image gateway path").into_response();
+    };
+    if request.method() != Method::POST {
+        return (StatusCode::METHOD_NOT_ALLOWED, "image endpoint requires POST").into_response();
+    }
+    if !is_json_request(request.headers()) {
+        return (StatusCode::UNSUPPORTED_MEDIA_TYPE, "image endpoint requires JSON")
+            .into_response();
+    }
+    let headers = request.headers().clone();
+    let Some(secret) = bearer_secret(&headers) else {
+        return (StatusCode::UNAUTHORIZED, "missing bearer token").into_response();
+    };
+    let key = match state.control.authenticate_bearer_secret(secret).await {
+        Ok(Some(key)) => key,
+        Ok(None) => return (StatusCode::UNAUTHORIZED, "invalid bearer token").into_response(),
+        Err(err) => {
+            tracing::warn!(error = %err, "codex image authentication failed");
+            return (StatusCode::INTERNAL_SERVER_ERROR, "authentication backend error")
+                .into_response();
+        },
+    };
+    if let Some(response) = reject_key(&key) {
+        return response;
+    }
+    let body = match to_bytes(request.into_body(), MAX_IMAGE_REQUEST_BODY_BYTES).await {
+        Ok(body) => body,
+        Err(_) => return (StatusCode::BAD_REQUEST, "invalid image request body").into_response(),
+    };
+    let payload = match serde_json::from_slice::<Value>(&body) {
+        Ok(payload) => payload,
+        Err(_) => {
+            return (StatusCode::BAD_REQUEST, "request body must be valid JSON").into_response()
+        },
+    };
+    let image_request = match parse_image_request(endpoint, payload) {
+        Ok(image_request) => image_request,
+        Err(err) => return (err.status, err.message).into_response(),
+    };
+    let response = dispatch_image_request(state.as_ref(), ImageDispatchRequest {
+        request_id: &request_id,
+        started,
+        headers: &headers,
+        key: &key,
+        endpoint_name: endpoint_name(endpoint),
+        upstream_path: upstream_image_path(endpoint),
+        image_request,
+    })
+    .await;
+    response
+}
+
+struct ImageDispatchRequest<'a> {
+    request_id: &'a str,
+    started: Instant,
+    headers: &'a HeaderMap,
+    key: &'a AuthenticatedKey,
+    endpoint_name: &'static str,
+    upstream_path: &'a str,
+    image_request: llm_access_codex_image::request::CodexImageRequest,
+}
+
+fn reject_key(key: &AuthenticatedKey) -> Option<axum::response::Response> {
+    if key.status != KEY_STATUS_ACTIVE {
+        return Some((StatusCode::FORBIDDEN, "llm key is not active").into_response());
+    }
+    if ProviderType::from_storage_str(&key.provider_type) != Some(ProviderType::Codex)
+        || ProtocolFamily::from_storage_str(&key.protocol_family) != Some(ProtocolFamily::OpenAi)
+    {
+        return Some(
+            (StatusCode::FORBIDDEN, "llm key does not match codex image route").into_response(),
+        );
+    }
+    if key.remaining_billable() <= 0 {
+        return Some((StatusCode::TOO_MANY_REQUESTS, "quota_exceeded").into_response());
+    }
+    None
+}
+
+async fn dispatch_image_request(
+    state: &AppState,
+    ctx: ImageDispatchRequest<'_>,
+) -> axum::response::Response {
+    let candidates = match state.control.resolve_codex_route_candidates(ctx.key).await {
+        Ok(candidates) => candidates,
+        Err(err) => {
+            tracing::warn!(error = %err, "codex image route lookup failed");
+            return (StatusCode::INTERNAL_SERVER_ERROR, "route store error").into_response();
+        },
+    };
+    let candidates = match eligible_image_routes(candidates) {
+        Ok(candidates) => candidates,
+        Err(err) => return (err.status, err.message).into_response(),
+    };
+    let mut failover_count = 0_u64;
+    let mut concurrency_blocked = 0_usize;
+    let mut last_error_class = None::<String>;
+    for candidate in candidates {
+        let Some(route) = hydrate_codex_image_route(state, candidate).await else {
+            failover_count += 1;
+            last_error_class = Some("auth_missing".to_string());
+            continue;
+        };
+        if access_token_expired(&route.auth_json) {
+            failover_count += 1;
+            last_error_class = Some("auth_expired".to_string());
+            continue;
+        }
+        let Some(access_token) = access_token_from_auth_json(&route.auth_json) else {
+            failover_count += 1;
+            last_error_class = Some("auth_missing".to_string());
+            continue;
+        };
+        let Some(_permit) = state.limiter.try_acquire(
+            &route.account_name,
+            Some(route.account_codex_image_generation_max_concurrency),
+        ) else {
+            concurrency_blocked += 1;
+            continue;
+        };
+        let client = match provider_client(route.proxy.as_ref()) {
+            Ok(client) => client,
+            Err(err) => {
+                tracing::warn!(account = %route.account_name, error = %err, "codex image client build failed");
+                failover_count += 1;
+                last_error_class = Some("proxy_client".to_string());
+                continue;
+            },
+        };
+        let upstream_url = compute_codex_upstream_url(&state.upstream_base, ctx.upstream_path);
+        let request_builder = add_image_upstream_headers(
+            client.post(upstream_url),
+            ctx.headers,
+            &access_token,
+            account_id_from_auth_json(&route.auth_json),
+            fedramp_from_auth_json(&route.auth_json),
+            &state.codex_client_version,
+        )
+        .body(ctx.image_request.raw.to_string());
+        let upstream = match request_builder.send().await {
+            Ok(response) => response,
+            Err(err) => {
+                tracing::warn!(account = %route.account_name, error = %err, "codex image upstream request failed");
+                failover_count += 1;
+                last_error_class = Some("upstream_request".to_string());
+                continue;
+            },
+        };
+        let status = upstream.status();
+        let headers = upstream.headers().clone();
+        let bytes = match upstream.bytes().await {
+            Ok(bytes) => bytes,
+            Err(err) => {
+                tracing::warn!(account = %route.account_name, error = %err, "codex image upstream response read failed");
+                failover_count += 1;
+                last_error_class = Some("upstream_body".to_string());
+                continue;
+            },
+        };
+        let metrics = response_image_metrics(&bytes);
+        let usage_tokens = usage_tokens_from_response(&bytes);
+        log_image_event(
+            state,
+            ctx.request_id,
+            ctx.key,
+            Some(&route.account_name),
+            ctx.endpoint_name,
+            &ctx.image_request,
+            UpstreamLogInput {
+                status: Some(status.as_u16()),
+                duration_ms: duration_ms(ctx.started),
+                failover_count,
+                error_class: if status.is_success() {
+                    None
+                } else {
+                    Some(status_error_class(status))
+                },
+                response_image_count: metrics.image_count,
+                response_image_bytes: metrics.image_bytes,
+                usage_tokens,
+                usage_missing: usage_tokens.is_none(),
+            },
+        );
+        if should_failover_status(status) {
+            failover_count += 1;
+            last_error_class = Some(status_error_class(status).to_string());
+            continue;
+        }
+        return upstream_response(status, &headers, bytes);
+    }
+    let status = if concurrency_blocked > 0 {
+        StatusCode::TOO_MANY_REQUESTS
+    } else {
+        StatusCode::BAD_GATEWAY
+    };
+    log_image_event(
+        state,
+        ctx.request_id,
+        ctx.key,
+        None,
+        ctx.endpoint_name,
+        &ctx.image_request,
+        UpstreamLogInput {
+            status: Some(status.as_u16()),
+            duration_ms: duration_ms(ctx.started),
+            failover_count,
+            error_class: Some(last_error_class.as_deref().unwrap_or("no_eligible_account")),
+            response_image_count: None,
+            response_image_bytes: None,
+            usage_tokens: None,
+            usage_missing: true,
+        },
+    );
+    (status, "all eligible codex image accounts failed for this request").into_response()
+}
+
+async fn hydrate_codex_image_route(
+    state: &AppState,
+    candidate: ProviderCodexRoute,
+) -> Option<ProviderCodexRoute> {
+    let hydrated = state
+        .control
+        .resolve_codex_account_route(&candidate.account_name)
+        .await
+        .ok()
+        .flatten()?;
+    Some(ProviderCodexRoute {
+        account_name: candidate.account_name,
+        account_group_id_at_event: candidate.account_group_id_at_event,
+        route_strategy_at_event: candidate.route_strategy_at_event,
+        auth_json: hydrated.auth_json,
+        map_gpt53_codex_to_spark: candidate.map_gpt53_codex_to_spark,
+        auth_refresh_enabled: candidate.auth_refresh_enabled,
+        codex_fast_enabled: candidate.codex_fast_enabled,
+        codex_strict_session_rejection_enabled: candidate.codex_strict_session_rejection_enabled,
+        codex_image_generation_enabled: candidate.codex_image_generation_enabled,
+        request_max_concurrency: candidate.request_max_concurrency,
+        request_min_start_interval_ms: candidate.request_min_start_interval_ms,
+        account_request_max_concurrency: candidate.account_request_max_concurrency,
+        account_request_min_start_interval_ms: candidate.account_request_min_start_interval_ms,
+        account_codex_image_generation_enabled: candidate.account_codex_image_generation_enabled,
+        account_codex_image_generation_max_concurrency: candidate
+            .account_codex_image_generation_max_concurrency,
+        cached_error_message: candidate
+            .cached_error_message
+            .or(hydrated.cached_error_message),
+        proxy: candidate.proxy.or(hydrated.proxy),
+    })
+}
+
+fn add_image_upstream_headers(
+    builder: reqwest::RequestBuilder,
+    headers: &HeaderMap,
+    access_token: &str,
+    account_id: Option<String>,
+    fedramp: bool,
+    codex_client_version: &str,
+) -> reqwest::RequestBuilder {
+    let mut builder = builder
+        .bearer_auth(access_token)
+        .header(reqwest::header::ACCEPT, "application/json")
+        .header(reqwest::header::CONTENT_TYPE, "application/json")
+        .header(
+            reqwest::header::USER_AGENT,
+            header_value(headers, header::USER_AGENT.as_str())
+                .unwrap_or_else(|| codex_user_agent(codex_client_version)),
+        )
+        .header(
+            reqwest::header::HeaderName::from_static("originator"),
+            header_value(headers, "originator").unwrap_or_else(|| "codex_cli_rs".to_string()),
+        );
+    for header_name in [
+        "openai-beta",
+        "x-openai-subagent",
+        "x-codex-beta-features",
+        "x-codex-installation-id",
+        "traceparent",
+        "tracestate",
+        "baggage",
+    ] {
+        if let Some(value) = header_value(headers, header_name) {
+            builder = builder.header(header_name, value);
+        }
+    }
+    if let Some(account_id) = account_id {
+        builder = builder.header("chatgpt-account-id", account_id);
+    }
+    if fedramp {
+        builder = builder.header("x-openai-fedramp", "true");
+    }
+    builder
+}
+
+fn provider_client(proxy: Option<&ProviderProxyConfig>) -> anyhow::Result<reqwest::Client> {
+    let mut builder = reqwest::Client::builder()
+        .pool_idle_timeout(Duration::from_secs(90))
+        .pool_max_idle_per_host(32)
+        .tcp_keepalive(Duration::from_secs(30));
+    if let Some(proxy_config) = proxy {
+        let mut proxy = reqwest::Proxy::all(&proxy_config.proxy_url)?;
+        if let Some(username) = proxy_config.proxy_username.as_deref() {
+            proxy =
+                proxy.basic_auth(username, proxy_config.proxy_password.as_deref().unwrap_or(""));
+        }
+        builder = builder.proxy(proxy);
+    }
+    Ok(builder.build()?)
+}
+
+fn upstream_response(
+    status: StatusCode,
+    headers: &reqwest::header::HeaderMap,
+    bytes: Bytes,
+) -> axum::response::Response {
+    let mut builder = Response::builder().status(status);
+    if let Some(content_type) = headers.get(reqwest::header::CONTENT_TYPE) {
+        builder = builder.header(header::CONTENT_TYPE, content_type);
+    }
+    builder.body(Body::from(bytes)).unwrap_or_else(|_| {
+        (StatusCode::BAD_GATEWAY, "failed to build upstream image response").into_response()
+    })
+}
+
+fn log_image_event(
+    state: &AppState,
+    request_id: &str,
+    key: &AuthenticatedKey,
+    account_name: Option<&str>,
+    endpoint: &str,
+    image_request: &llm_access_codex_image::request::CodexImageRequest,
+    upstream: UpstreamLogInput<'_>,
+) {
+    let input_images = image_request
+        .images
+        .iter()
+        .map(String::as_str)
+        .collect::<Vec<_>>();
+    let event = build_image_log_event(ImageLogInput {
+        request_id,
+        key_id: &key.key_id,
+        key_name: &key.key_name,
+        account_name,
+        endpoint,
+        prompt: &image_request.prompt,
+        size: image_request.size.as_deref(),
+        quality: image_request.quality.as_deref(),
+        n: image_request.n,
+        input_images: &input_images,
+        upstream,
+    });
+    if let Err(err) = state
+        .image_log
+        .lock()
+        .expect("codex image log mutex poisoned")
+        .append(&event)
+    {
+        tracing::warn!(error = %err, "codex image request log write failed");
+    }
+}
+
+#[derive(Debug, Default)]
+struct ImageResponseMetrics {
+    image_count: Option<u64>,
+    image_bytes: Option<u64>,
+}
+
+fn response_image_metrics(bytes: &[u8]) -> ImageResponseMetrics {
+    let Ok(value) = serde_json::from_slice::<Value>(bytes) else {
+        return ImageResponseMetrics::default();
+    };
+    let Some(items) = value.get("data").and_then(Value::as_array) else {
+        return ImageResponseMetrics::default();
+    };
+    let mut image_bytes = 0_u64;
+    for item in items {
+        if let Some(b64) = item.get("b64_json").and_then(Value::as_str) {
+            image_bytes = image_bytes.saturating_add(approx_base64_bytes(b64));
+        }
+    }
+    ImageResponseMetrics {
+        image_count: Some(items.len() as u64),
+        image_bytes: (image_bytes > 0).then_some(image_bytes),
+    }
+}
+
+fn usage_tokens_from_response(bytes: &[u8]) -> Option<u64> {
+    let value = serde_json::from_slice::<Value>(bytes).ok()?;
+    value
+        .pointer("/usage/total_tokens")
+        .and_then(Value::as_u64)
+        .or_else(|| value.pointer("/usage/tokens").and_then(Value::as_u64))
+}
+
+fn approx_base64_bytes(value: &str) -> u64 {
+    let padding = value.chars().rev().take_while(|ch| *ch == '=').count() as u64;
+    ((value.len() as u64).saturating_mul(3) / 4).saturating_sub(padding)
+}
+
+fn access_token_from_auth_json(auth_json: &str) -> Option<String> {
+    let value = serde_json::from_str::<Value>(auth_json).ok()?;
+    json_string_any(&value, &["access_token", "accessToken"]).or_else(|| {
+        value
+            .get("tokens")
+            .and_then(|tokens| json_string_any(tokens, &["access_token", "accessToken"]))
+    })
+}
+
+fn account_id_from_auth_json(auth_json: &str) -> Option<String> {
+    let value = serde_json::from_str::<Value>(auth_json).ok()?;
+    json_string_any(&value, &["account_id", "accountId"]).or_else(|| {
+        value
+            .get("account")
+            .and_then(|account| json_string_any(account, &["id", "account_id", "accountId"]))
+    })
+}
+
+fn fedramp_from_auth_json(auth_json: &str) -> bool {
+    serde_json::from_str::<Value>(auth_json)
+        .ok()
+        .and_then(|value| {
+            value
+                .get("is_fedramp_account")
+                .or_else(|| value.get("isFedrampAccount"))
+                .and_then(Value::as_bool)
+        })
+        .unwrap_or(false)
+}
+
+fn json_string_any(value: &Value, keys: &[&str]) -> Option<String> {
+    keys.iter()
+        .find_map(|key| value.get(*key).and_then(Value::as_str))
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToString::to_string)
+}
+
+fn access_token_expired(auth_json: &str) -> bool {
+    codex_auth_access_token_expires_at_ms(auth_json)
+        .is_some_and(|expires_at| i64::try_from(now_ms()).unwrap_or(i64::MAX) >= expires_at)
+}
+
+fn is_json_request(headers: &HeaderMap) -> bool {
+    headers
+        .get(header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(|value| value.split(';').next().unwrap_or("").trim())
+        .is_some_and(|value| value.eq_ignore_ascii_case("application/json"))
+}
+
+fn bearer_secret(headers: &HeaderMap) -> Option<&str> {
+    let value = headers.get(header::AUTHORIZATION)?.to_str().ok()?;
+    let (scheme, token) = value.split_once(' ')?;
+    if !scheme.eq_ignore_ascii_case("bearer") {
+        return None;
+    }
+    let token = token.trim();
+    (!token.is_empty()).then_some(token)
+}
+
+fn header_value(headers: &HeaderMap, name: &str) -> Option<String> {
+    headers
+        .get(name)
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToString::to_string)
+}
+
+fn codex_upstream_base_url() -> String {
+    std::env::var("CODEX_UPSTREAM_BASE_URL")
+        .or_else(|_| std::env::var("STATICFLOW_LLM_GATEWAY_UPSTREAM_BASE_URL"))
+        .map(|value| llm_access_codex::request::normalize_upstream_base_url(&value))
+        .unwrap_or_else(|_| DEFAULT_UPSTREAM_BASE_URL.to_string())
+}
+
+fn compute_codex_upstream_url(base: &str, path: &str) -> String {
+    let base = base.trim_end_matches('/');
+    if base.contains("/backend-api/codex") && path.starts_with("/v1/") {
+        format!("{}{}", base, path.trim_start_matches("/v1"))
+    } else if base.ends_with("/v1") && path.starts_with("/v1") {
+        format!("{}{}", base.trim_end_matches("/v1"), path)
+    } else {
+        format!("{base}{path}")
+    }
+}
+
+fn normalize_codex_client_version(raw: &str) -> Option<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() || trimmed.len() > 64 {
+        return None;
+    }
+    trimmed
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_'))
+        .then(|| trimmed.to_string())
+}
+
+fn codex_user_agent(client_version: &str) -> String {
+    format!("codex_cli_rs/{client_version}")
+}
+
+fn status_error_class(status: StatusCode) -> &'static str {
+    if status == StatusCode::UNAUTHORIZED || status == StatusCode::FORBIDDEN {
+        "auth"
+    } else if status == StatusCode::TOO_MANY_REQUESTS {
+        "rate_limited"
+    } else if status.is_server_error() {
+        "upstream_server"
+    } else if status.is_client_error() {
+        "client_error"
+    } else {
+        "upstream_status"
+    }
+}
+
+fn endpoint_name(endpoint: llm_access_codex_image::request::CodexImageEndpoint) -> &'static str {
+    match endpoint {
+        llm_access_codex_image::request::CodexImageEndpoint::Generations => "generations",
+        llm_access_codex_image::request::CodexImageEndpoint::Edits => "edits",
+    }
+}
+
+fn duration_ms(started: Instant) -> u64 {
+    started.elapsed().as_millis() as u64
+}
+
+fn new_request_id() -> String {
+    format!("codex-img-{}-{}", std::process::id(), now_ms())
+}
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis() as u64)
+        .unwrap_or(0)
+}
diff --git a/crates/llm-access-codex-image/src/request.rs b/crates/llm-access-codex-image/src/request.rs
new file mode 100644
index 00000000..0dfdef15
--- /dev/null
+++ b/crates/llm-access-codex-image/src/request.rs
@@ -0,0 +1,240 @@
+use axum::http::StatusCode;
+use serde_json::{Map, Value};
+
+const DEFAULT_MODEL: &str = "gpt-image-2";
+const ALLOWED_FIELDS_GENERATIONS: &[&str] =
+    &["model", "prompt", "n", "size", "quality", "background"];
+const ALLOWED_FIELDS_EDITS: &[&str] =
+    &["model", "prompt", "n", "size", "quality", "background", "images"];
+const ALLOWED_SIZES: &[&str] =
+    &["auto", "1024x1024", "1536x1024", "1024x1536", "2048x1152", "1152x2048"];
+const ALLOWED_QUALITIES: &[&str] = &["auto", "low", "medium", "high"];
+const ALLOWED_BACKGROUNDS: &[&str] = &["auto", "transparent", "opaque"];
+const ALLOWED_DATA_IMAGE_PREFIXES: &[&str] = &[
+    "data:image/png;base64,",
+    "data:image/jpeg;base64,",
+    "data:image/jpg;base64,",
+    "data:image/webp;base64,",
+];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+/// Supported image API endpoints after public path normalization.
+pub enum CodexImageEndpoint {
+    /// Image generation endpoint.
+    Generations,
+    /// Image edit endpoint.
+    Edits,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+/// Validated image request accepted by the standalone gateway.
+pub struct CodexImageRequest {
+    /// OpenAI image model name. Currently always `gpt-image-2`.
+    pub model: String,
+    /// User prompt passed to the upstream image API.
+    pub prompt: String,
+    /// Requested number of images.
+    pub n: u64,
+    /// Optional image size parameter.
+    pub size: Option<String>,
+    /// Optional quality parameter.
+    pub quality: Option<String>,
+    /// Optional background parameter.
+    pub background: Option<String>,
+    /// Edit input image sources.
+    pub images: Vec<String>,
+    /// Sanitized original JSON object forwarded to upstream.
+    pub raw: Value,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+/// Validation error returned before any upstream request is attempted.
+pub struct CodexImageRequestError {
+    /// HTTP status to return to the client.
+    pub status: StatusCode,
+    /// Human-readable error message.
+    pub message: String,
+}
+
+impl CodexImageRequestError {
+    fn bad_request(message: impl Into<String>) -> Self {
+        Self {
+            status: StatusCode::BAD_REQUEST,
+            message: message.into(),
+        }
+    }
+}
+
+/// Maps all supported public aliases to the internal image endpoint enum.
+pub fn normalize_image_gateway_path(path: &str) -> Option<CodexImageEndpoint> {
+    match path {
+        "/v1/images/generations"
+        | "/api/codex-gateway/images/generations"
+        | "/api/codex-gateway/v1/images/generations"
+        | "/api/llm-gateway/v1/images/generations" => Some(CodexImageEndpoint::Generations),
+        "/v1/images/edits"
+        | "/api/codex-gateway/images/edits"
+        | "/api/codex-gateway/v1/images/edits"
+        | "/api/llm-gateway/v1/images/edits" => Some(CodexImageEndpoint::Edits),
+        _ => None,
+    }
+}
+
+/// Returns the upstream image API path for a normalized endpoint.
+pub fn upstream_image_path(endpoint: CodexImageEndpoint) -> &'static str {
+    match endpoint {
+        CodexImageEndpoint::Generations => "/v1/images/generations",
+        CodexImageEndpoint::Edits => "/v1/images/edits",
+    }
+}
+
+/// Validates a JSON image request and rejects unsupported parameters.
+pub fn parse_image_request(
+    endpoint: CodexImageEndpoint,
+    payload: Value,
+) -> Result<CodexImageRequest, CodexImageRequestError> {
+    let object = payload
+        .as_object()
+        .ok_or_else(|| CodexImageRequestError::bad_request("request body must be a JSON object"))?;
+    let allowed_fields = match endpoint {
+        CodexImageEndpoint::Generations => ALLOWED_FIELDS_GENERATIONS,
+        CodexImageEndpoint::Edits => ALLOWED_FIELDS_EDITS,
+    };
+    reject_unknown_fields(object, allowed_fields)?;
+
+    let model = optional_string(object, "model")?.unwrap_or_else(|| DEFAULT_MODEL.to_string());
+    if model != DEFAULT_MODEL {
+        return Err(CodexImageRequestError::bad_request("model must be gpt-image-2"));
+    }
+
+    let prompt = required_string(object, "prompt")?;
+    if prompt.trim().is_empty() {
+        return Err(CodexImageRequestError::bad_request("prompt is required"));
+    }
+
+    let n = optional_u64(object, "n")?.unwrap_or(1);
+    if !(1..=4).contains(&n) {
+        return Err(CodexImageRequestError::bad_request("n must be between 1 and 4"));
+    }
+
+    let size = optional_enum_string(object, "size", ALLOWED_SIZES)?;
+    let quality = optional_enum_string(object, "quality", ALLOWED_QUALITIES)?;
+    let background = optional_enum_string(object, "background", ALLOWED_BACKGROUNDS)?;
+    let images = parse_edit_images(endpoint, object)?;
+
+    Ok(CodexImageRequest {
+        model,
+        prompt,
+        n,
+        size,
+        quality,
+        background,
+        images,
+        raw: Value::Object(object.clone()),
+    })
+}
+
+fn reject_unknown_fields(
+    object: &Map<String, Value>,
+    allowed_fields: &[&str],
+) -> Result<(), CodexImageRequestError> {
+    for key in object.keys() {
+        if !allowed_fields.contains(&key.as_str()) {
+            return Err(CodexImageRequestError::bad_request(format!("unknown field `{key}`")));
+        }
+    }
+    Ok(())
+}
+
+fn required_string(
+    object: &Map<String, Value>,
+    field: &str,
+) -> Result<String, CodexImageRequestError> {
+    optional_string(object, field)?
+        .ok_or_else(|| CodexImageRequestError::bad_request(format!("{field} is required")))
+}
+
+fn optional_string(
+    object: &Map<String, Value>,
+    field: &str,
+) -> Result<Option<String>, CodexImageRequestError> {
+    match object.get(field) {
+        Some(Value::String(value)) => Ok(Some(value.clone())),
+        Some(_) => Err(CodexImageRequestError::bad_request(format!("{field} must be a string"))),
+        None => Ok(None),
+    }
+}
+
+fn optional_u64(
+    object: &Map<String, Value>,
+    field: &str,
+) -> Result<Option<u64>, CodexImageRequestError> {
+    match object.get(field) {
+        Some(Value::Number(value)) => value.as_u64().map(Some).ok_or_else(|| {
+            CodexImageRequestError::bad_request(format!("{field} must be an integer"))
+        }),
+        Some(_) => Err(CodexImageRequestError::bad_request(format!("{field} must be an integer"))),
+        None => Ok(None),
+    }
+}
+
+fn optional_enum_string(
+    object: &Map<String, Value>,
+    field: &str,
+    allowed: &[&str],
+) -> Result<Option<String>, CodexImageRequestError> {
+    let Some(value) = optional_string(object, field)? else {
+        return Ok(None);
+    };
+    if allowed.contains(&value.as_str()) {
+        Ok(Some(value))
+    } else {
+        Err(CodexImageRequestError::bad_request(format!("{field} has unsupported value")))
+    }
+}
+
+fn parse_edit_images(
+    endpoint: CodexImageEndpoint,
+    object: &Map<String, Value>,
+) -> Result<Vec<String>, CodexImageRequestError> {
+    if endpoint == CodexImageEndpoint::Generations {
+        return Ok(Vec::new());
+    }
+    let Some(value) = object.get("images") else {
+        return Err(CodexImageRequestError::bad_request("images is required"));
+    };
+    let images = value
+        .as_array()
+        .ok_or_else(|| CodexImageRequestError::bad_request("images must be an array"))?;
+    if images.is_empty() || images.len() > 5 {
+        return Err(CodexImageRequestError::bad_request(
+            "images must contain between 1 and 5 entries",
+        ));
+    }
+    images
+        .iter()
+        .map(|value| {
+            let source = value.as_str().ok_or_else(|| {
+                CodexImageRequestError::bad_request("image source must be a string")
+            })?;
+            validate_image_source(source)?;
+            Ok(source.to_string())
+        })
+        .collect()
+}
+
+fn validate_image_source(source: &str) -> Result<(), CodexImageRequestError> {
+    let lower = source.to_ascii_lowercase();
+    if lower.starts_with("http://") || lower.starts_with("https://") {
+        return Ok(());
+    }
+    if ALLOWED_DATA_IMAGE_PREFIXES
+        .iter()
+        .any(|prefix| lower.starts_with(prefix))
+    {
+        return Ok(());
+    }
+    Err(CodexImageRequestError::bad_request(
+        "image source must be an http(s) URL or supported image data URL",
+    ))
+}
diff --git a/crates/llm-access-codex-image/tests/codex_image_dispatch.rs b/crates/llm-access-codex-image/tests/codex_image_dispatch.rs
new file mode 100644
index 00000000..df60a3bb
--- /dev/null
+++ b/crates/llm-access-codex-image/tests/codex_image_dispatch.rs
@@ -0,0 +1,129 @@
+//! Routing, concurrency, and logging coverage for Codex image dispatch.
+
+use axum::http::StatusCode;
+use llm_access_codex_image::{
+    dispatch::{eligible_image_routes, should_failover_status},
+    limiter::{image_account_limiter_scope, ImageAccountLimiter},
+    logging::{build_image_log_event, ImageLogInput, UpstreamLogInput},
+};
+use llm_access_core::{provider::RouteStrategy, store::ProviderCodexRoute};
+
+fn route(account_name: &str, key_enabled: bool, account_enabled: bool) -> ProviderCodexRoute {
+    ProviderCodexRoute {
+        account_name: account_name.to_string(),
+        account_group_id_at_event: None,
+        route_strategy_at_event: RouteStrategy::Auto,
+        auth_json: r#"{"access_token":"token"}"#.to_string(),
+        map_gpt53_codex_to_spark: false,
+        auth_refresh_enabled: true,
+        codex_fast_enabled: true,
+        codex_strict_session_rejection_enabled: false,
+        codex_image_generation_enabled: key_enabled,
+        request_max_concurrency: None,
+        request_min_start_interval_ms: None,
+        account_request_max_concurrency: None,
+        account_request_min_start_interval_ms: None,
+        account_codex_image_generation_enabled: account_enabled,
+        account_codex_image_generation_max_concurrency:
+            llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
+        cached_error_message: None,
+        proxy: None,
+    }
+}
+
+#[test]
+fn image_route_selection_rejects_disabled_key_and_disabled_accounts() {
+    let err = eligible_image_routes(vec![route("codex-a", false, true)])
+        .expect_err("key-level image switch must be enforced");
+    assert_eq!(err.status, StatusCode::FORBIDDEN);
+
+    let err = eligible_image_routes(vec![route("codex-a", true, false)])
+        .expect_err("account-level image switch must be enforced");
+    assert_eq!(err.status, StatusCode::SERVICE_UNAVAILABLE);
+
+    let selected =
+        eligible_image_routes(vec![route("codex-a", true, false), route("codex-b", true, true)])
+            .expect("image-enabled accounts should be selected");
+    assert_eq!(selected.len(), 1);
+    assert_eq!(selected[0].account_name, "codex-b");
+}
+
+#[tokio::test]
+async fn image_account_limiter_uses_independent_scope_and_default_limit() {
+    assert_eq!(image_account_limiter_scope("codex-a"), "account:codex-image:codex-a");
+
+    let limiter = ImageAccountLimiter::default();
+    let first = limiter
+        .try_acquire("codex-a", None)
+        .expect("first permit should be available");
+    let second = limiter
+        .try_acquire("codex-a", None)
+        .expect("second permit should be available");
+    let third = limiter
+        .try_acquire("codex-a", None)
+        .expect("third permit should be available");
+    assert!(limiter.try_acquire("codex-a", None).is_none());
+    drop(first);
+    assert!(limiter.try_acquire("codex-a", None).is_some());
+    drop(second);
+    drop(third);
+}
+
+#[tokio::test]
+async fn image_account_limiter_honors_lowered_account_limit() {
+    let limiter = ImageAccountLimiter::default();
+    let first = limiter
+        .try_acquire("codex-a", Some(3))
+        .expect("first permit should be available");
+    let second = limiter
+        .try_acquire("codex-a", Some(3))
+        .expect("second permit should be available");
+
+    assert!(limiter.try_acquire("codex-a", Some(1)).is_none());
+    drop(first);
+    assert!(limiter.try_acquire("codex-a", Some(1)).is_none());
+    drop(second);
+    assert!(limiter.try_acquire("codex-a", Some(1)).is_some());
+}
+
+#[test]
+fn image_failover_only_retries_transient_or_auth_failures() {
+    assert!(!should_failover_status(StatusCode::BAD_REQUEST));
+    assert!(should_failover_status(StatusCode::UNAUTHORIZED));
+    assert!(should_failover_status(StatusCode::FORBIDDEN));
+    assert!(should_failover_status(StatusCode::TOO_MANY_REQUESTS));
+    assert!(should_failover_status(StatusCode::BAD_GATEWAY));
+}
+
+#[test]
+fn image_log_event_redacts_prompt_and_image_payloads() {
+    let event = build_image_log_event(ImageLogInput {
+        request_id: "req-1",
+        key_id: "key-1",
+        key_name: "Key One",
+        account_name: Some("codex-a"),
+        endpoint: "edits",
+        prompt: "draw an exact scene with confidential text",
+        size: Some("1024x1024"),
+        quality: Some("high"),
+        n: 2,
+        input_images: &["data:image/png;base64,AAABBBCCC", "https://example.com/input.png"],
+        upstream: UpstreamLogInput {
+            status: Some(200),
+            duration_ms: 17,
+            failover_count: 1,
+            error_class: None,
+            response_image_count: Some(2),
+            response_image_bytes: Some(4096),
+            usage_tokens: None,
+            usage_missing: true,
+        },
+    });
+    let encoded = serde_json::to_string(&event).expect("encode log event");
+
+    assert!(!encoded.contains("AAABBBCCC"));
+    assert!(!encoded.contains("data:image"));
+    assert!(!encoded.contains("confidential text"));
+    assert!(encoded.contains("prompt_hash"));
+    assert!(encoded.contains("input_image_count"));
+}
diff --git a/crates/llm-access-codex-image/tests/codex_image_request.rs b/crates/llm-access-codex-image/tests/codex_image_request.rs
new file mode 100644
index 00000000..b94a38ea
--- /dev/null
+++ b/crates/llm-access-codex-image/tests/codex_image_request.rs
@@ -0,0 +1,99 @@
+//! Request validation coverage for the standalone Codex image gateway.
+
+use llm_access_codex_image::request::{
+    normalize_image_gateway_path, parse_image_request, CodexImageEndpoint,
+};
+use serde_json::json;
+
+#[test]
+fn codex_image_path_normalization_accepts_public_aliases() {
+    assert_eq!(
+        normalize_image_gateway_path("/v1/images/generations"),
+        Some(CodexImageEndpoint::Generations)
+    );
+    assert_eq!(
+        normalize_image_gateway_path("/api/codex-gateway/images/edits"),
+        Some(CodexImageEndpoint::Edits)
+    );
+    assert_eq!(
+        normalize_image_gateway_path("/api/llm-gateway/v1/images/generations"),
+        Some(CodexImageEndpoint::Generations)
+    );
+    assert_eq!(normalize_image_gateway_path("/v1/responses"), None);
+}
+
+#[test]
+fn codex_image_generation_defaults_model_and_rejects_unknown_fields() {
+    let request = parse_image_request(
+        CodexImageEndpoint::Generations,
+        json!({
+            "prompt": "draw a lake",
+            "size": "1024x1024",
+            "quality": "high",
+            "n": 2
+        }),
+    )
+    .expect("valid generation request");
+
+    assert_eq!(request.model, "gpt-image-2");
+    assert_eq!(request.n, 2);
+
+    let err = parse_image_request(
+        CodexImageEndpoint::Generations,
+        json!({
+            "prompt": "draw a lake",
+            "style": "watercolor"
+        }),
+    )
+    .expect_err("unknown field must be rejected");
+    assert_eq!(err.status.as_u16(), 400);
+    assert!(err.message.contains("unknown field"));
+}
+
+#[test]
+fn codex_image_generation_rejects_wrong_model_empty_prompt_and_bad_n() {
+    for payload in [
+        json!({"model": "gpt-image-1", "prompt": "x"}),
+        json!({"model": "gpt-image-2", "prompt": "   "}),
+        json!({"model": "gpt-image-2", "prompt": "x", "n": 0}),
+        json!({"model": "gpt-image-2", "prompt": "x", "n": 5}),
+    ] {
+        let err = parse_image_request(CodexImageEndpoint::Generations, payload)
+            .expect_err("invalid generation payload must be rejected");
+        assert_eq!(err.status.as_u16(), 400);
+    }
+}
+
+#[test]
+fn codex_image_edits_validate_image_sources_and_count() {
+    parse_image_request(
+        CodexImageEndpoint::Edits,
+        json!({
+            "prompt": "change the sky",
+            "images": [
+                "data:image/png;base64,aGVsbG8=",
+                "https://example.com/input.webp"
+            ]
+        }),
+    )
+    .expect("valid edit request");
+
+    for payload in [
+        json!({"prompt": "x", "images": []}),
+        json!({"prompt": "x", "images": [
+            "https://example.com/1.png",
+            "https://example.com/2.png",
+            "https://example.com/3.png",
+            "https://example.com/4.png",
+            "https://example.com/5.png",
+            "https://example.com/6.png"
+        ]}),
+        json!({"prompt": "x", "images": ["file:///tmp/a.png"]}),
+        json!({"prompt": "x", "images": ["./a.png"]}),
+        json!({"prompt": "x", "images": ["data:text/plain;base64,aGVsbG8="]}),
+    ] {
+        let err = parse_image_request(CodexImageEndpoint::Edits, payload)
+            .expect_err("invalid edit payload must be rejected");
+        assert_eq!(err.status.as_u16(), 400);
+    }
+}
diff --git a/crates/llm-access-core/src/store/codex_account.rs b/crates/llm-access-core/src/store/codex_account.rs
index 74e62225..dcaf0b30 100644
--- a/crates/llm-access-core/src/store/codex_account.rs
+++ b/crates/llm-access-core/src/store/codex_account.rs
@@ -33,6 +33,12 @@ pub struct AdminCodexAccount {
     pub request_max_concurrency: Option<u64>,
     /// Per-account request pacing interval.
     pub request_min_start_interval_ms: Option<u64>,
+    /// Whether this account may serve Codex image generation/edit requests.
+    #[serde(default)]
+    pub codex_image_generation_enabled: bool,
+    /// Per-account Codex image generation/edit concurrency cap.
+    #[serde(default = "default_codex_image_generation_max_concurrency")]
+    pub codex_image_generation_max_concurrency: u64,
     /// Proxy selection mode.
     pub proxy_mode: String,
     /// Fixed proxy config id when proxy mode is fixed.
@@ -262,10 +268,18 @@ pub struct AdminCodexAccountPatch {
     pub request_max_concurrency: Option<Option<u64>>,
     /// New per-account request pacing interval.
     pub request_min_start_interval_ms: Option<Option<u64>>,
+    /// New Codex image generation/edit account toggle.
+    pub codex_image_generation_enabled: Option<bool>,
+    /// New per-account Codex image generation/edit concurrency cap.
+    pub codex_image_generation_max_concurrency: Option<u64>,
     /// Update timestamp.
     pub updated_at_ms: i64,
 }
 
+const fn default_codex_image_generation_max_concurrency() -> u64 {
+    super::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY
+}
+
 /// Admin-facing summary for one Codex batch import job.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct AdminCodexImportJobSummary {
@@ -412,6 +426,9 @@ mod tests {
             auto_refresh_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency:
+                super::default_codex_image_generation_max_concurrency(),
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
diff --git a/crates/llm-access-core/src/store/empty.rs b/crates/llm-access-core/src/store/empty.rs
index b918791f..0356395a 100644
--- a/crates/llm-access-core/src/store/empty.rs
+++ b/crates/llm-access-core/src/store/empty.rs
@@ -52,7 +52,8 @@ use super::{
         UsageChartPoint, UsageEventPage, UsageEventQuery, UsageEventTotals, UsageFilterOptions,
         UsageMetricsQuery, UsageMetricsSnapshot, UsageRollupApplyReport, UsageRollupBatch,
     },
-    DEFAULT_AUTH_CACHE_TTL_SECONDS, DEFAULT_CODEX_STATUS_REFRESH_SECONDS, KEY_STATUS_ACTIVE,
+    DEFAULT_AUTH_CACHE_TTL_SECONDS, DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
+    DEFAULT_CODEX_STATUS_REFRESH_SECONDS, KEY_STATUS_ACTIVE,
 };
 use crate::usage::UsageEvent;
 
@@ -371,6 +372,7 @@ impl AdminKeyStore for EmptyAdminKeyStore {
             request_min_start_interval_ms: key.request_min_start_interval_ms,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: false,
             kiro_request_validation_enabled: true,
             kiro_cache_estimation_enabled: true,
             kiro_zero_cache_debug_enabled: false,
@@ -595,6 +597,8 @@ impl AdminCodexAccountStore for EmptyAdminCodexAccountStore {
             auto_refresh_enabled: account.auto_refresh_enabled,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency: DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "none".to_string(),
diff --git a/crates/llm-access-core/src/store/keys.rs b/crates/llm-access-core/src/store/keys.rs
index daf90f3b..04a3ea2d 100644
--- a/crates/llm-access-core/src/store/keys.rs
+++ b/crates/llm-access-core/src/store/keys.rs
@@ -67,6 +67,9 @@ pub struct AdminKey {
     /// early for this key.
     #[serde(default)]
     pub codex_strict_session_rejection_enabled: bool,
+    /// Whether Codex image generation/edit requests are enabled for this key.
+    #[serde(default)]
+    pub codex_image_generation_enabled: bool,
     /// Whether Kiro request validation is enabled.
     pub kiro_request_validation_enabled: bool,
     /// Whether Kiro cache estimation is enabled.
@@ -352,6 +355,8 @@ pub struct AdminKeyPatch {
     pub codex_fast_enabled: Option<bool>,
     /// New Codex strict session-rejection toggle.
     pub codex_strict_session_rejection_enabled: Option<bool>,
+    /// New Codex image generation/edit toggle.
+    pub codex_image_generation_enabled: Option<bool>,
     /// New Kiro request-validation toggle.
     pub kiro_request_validation_enabled: Option<bool>,
     /// New Kiro cache-estimation toggle.
diff --git a/crates/llm-access-core/src/store/mod.rs b/crates/llm-access-core/src/store/mod.rs
index abe31413..4b689222 100644
--- a/crates/llm-access-core/src/store/mod.rs
+++ b/crates/llm-access-core/src/store/mod.rs
@@ -128,6 +128,8 @@ pub const DEFAULT_CODEX_FALLBACK_AFFINITY_TTL_SECONDS: u64 = 30 * 60;
 pub const DEFAULT_CODEX_FALLBACK_AFFINITY_PREFIX_BYTES: u64 = 4_096;
 /// Default minimum request body size before fallback affinity is used.
 pub const DEFAULT_CODEX_FALLBACK_AFFINITY_MIN_BODY_BYTES: u64 = 128;
+/// Default per-account concurrency for Codex image generation/edit requests.
+pub const DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY: u64 = 3;
 /// Default lower bound for randomized Kiro status refresh.
 pub const DEFAULT_KIRO_STATUS_REFRESH_MIN_INTERVAL_SECONDS: u64 = 240;
 /// Default upper bound for randomized Kiro status refresh.
diff --git a/crates/llm-access-core/src/store/routes.rs b/crates/llm-access-core/src/store/routes.rs
index 71d054d1..c2557130 100644
--- a/crates/llm-access-core/src/store/routes.rs
+++ b/crates/llm-access-core/src/store/routes.rs
@@ -57,6 +57,8 @@ pub struct ProviderCodexRoute {
     /// Whether fatal Codex session errors reject repeated requests for the same
     /// key/session before selecting another account.
     pub codex_strict_session_rejection_enabled: bool,
+    /// Whether this key is allowed to dispatch Codex image requests.
+    pub codex_image_generation_enabled: bool,
     /// Request concurrency cap configured on this key route.
     pub request_max_concurrency: Option<u64>,
     /// Minimum interval between request starts configured on this key route.
@@ -66,6 +68,10 @@ pub struct ProviderCodexRoute {
     /// Minimum interval between request starts configured on the selected
     /// account.
     pub account_request_min_start_interval_ms: Option<u64>,
+    /// Whether the selected account may be used for Codex image requests.
+    pub account_codex_image_generation_enabled: bool,
+    /// Image request concurrency cap configured on the selected account.
+    pub account_codex_image_generation_max_concurrency: u64,
     /// Cached account error message captured from the latest status view.
     pub cached_error_message: Option<String>,
     /// Resolved proxy settings for this upstream request.
diff --git a/crates/llm-access-migrations/migrations/postgres/0001_init.sql b/crates/llm-access-migrations/migrations/postgres/0001_init.sql
index 75c54ff5..ec942df2 100644
--- a/crates/llm-access-migrations/migrations/postgres/0001_init.sql
+++ b/crates/llm-access-migrations/migrations/postgres/0001_init.sql
@@ -29,6 +29,7 @@ CREATE TABLE IF NOT EXISTS llm_key_route_config (
     request_max_concurrency BIGINT,
     request_min_start_interval_ms BIGINT,
     codex_fast_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    codex_image_generation_enabled BOOLEAN NOT NULL DEFAULT FALSE,
     kiro_request_validation_enabled BOOLEAN NOT NULL DEFAULT FALSE,
     kiro_cache_estimation_enabled BOOLEAN NOT NULL DEFAULT FALSE,
     kiro_zero_cache_debug_enabled BOOLEAN NOT NULL DEFAULT FALSE,
diff --git a/crates/llm-access-migrations/migrations/postgres/0030_codex_image_generation_toggle.sql b/crates/llm-access-migrations/migrations/postgres/0030_codex_image_generation_toggle.sql
new file mode 100644
index 00000000..65491188
--- /dev/null
+++ b/crates/llm-access-migrations/migrations/postgres/0030_codex_image_generation_toggle.sql
@@ -0,0 +1,2 @@
+ALTER TABLE IF EXISTS llm_key_route_config
+    ADD COLUMN IF NOT EXISTS codex_image_generation_enabled BOOLEAN NOT NULL DEFAULT FALSE;
diff --git a/crates/llm-access-migrations/src/lib.rs b/crates/llm-access-migrations/src/lib.rs
index edb113e5..a7e4de91 100644
--- a/crates/llm-access-migrations/src/lib.rs
+++ b/crates/llm-access-migrations/src/lib.rs
@@ -143,6 +143,11 @@ const POSTGRES_MIGRATIONS: &[SqlMigration] = &[
         name: "codex_strict_session_rejection",
         sql: include_str!("../migrations/postgres/0029_codex_strict_session_rejection.sql"),
     },
+    SqlMigration {
+        version: 30,
+        name: "codex_image_generation_toggle",
+        sql: include_str!("../migrations/postgres/0030_codex_image_generation_toggle.sql"),
+    },
 ];
 
 /// Return target DuckDB migrations in execution order.
diff --git a/crates/llm-access-store/src/duckdb.rs b/crates/llm-access-store/src/duckdb.rs
index 5475021a..fbd5af8e 100644
--- a/crates/llm-access-store/src/duckdb.rs
+++ b/crates/llm-access-store/src/duckdb.rs
@@ -701,6 +701,7 @@ const DUCKDB_COMPACT_MAX_TEMP_DIRECTORY_SIZE: &str = "8GB";
 #[cfg(feature = "duckdb-runtime")]
 const DUCKDB_USAGE_CONNECTION_MAX_TEMP_DIRECTORY_SIZE: &str = "2GB";
 
+#[cfg(feature = "duckdb-runtime")]
 fn tiered_pending_dir(config: &TieredDuckDbUsageConfig) -> PathBuf {
     config.active_dir.join("pending")
 }
diff --git a/crates/llm-access-store/src/lib.rs b/crates/llm-access-store/src/lib.rs
index 32bc1d53..d03df0d9 100644
--- a/crates/llm-access-store/src/lib.rs
+++ b/crates/llm-access-store/src/lib.rs
@@ -14,6 +14,7 @@ pub(crate) mod records;
 /// Valkey-backed request-path cache primitives.
 pub mod request_cache;
 /// Postgres-backed archived usage catalog metadata.
+#[cfg(feature = "duckdb-runtime")]
 pub(crate) mod usage_catalog;
 
 /// Aggregated usage counters for one API key from analytics usage events.
diff --git a/crates/llm-access-store/src/postgres.rs b/crates/llm-access-store/src/postgres.rs
index 5c9d9f25..59a8fa9a 100644
--- a/crates/llm-access-store/src/postgres.rs
+++ b/crates/llm-access-store/src/postgres.rs
@@ -408,6 +408,8 @@ struct CodexAdminAccountListRow {
     proxy_config_id: Option<String>,
     request_max_concurrency: Option<i64>,
     request_min_start_interval_ms: Option<i64>,
+    codex_image_generation_enabled: bool,
+    codex_image_generation_max_concurrency: i64,
     last_refresh_at_ms: Option<i64>,
     last_error: Option<String>,
     access_token: Option<String>,
@@ -465,6 +467,8 @@ struct CodexAccountSettings {
     proxy_config_id: Option<String>,
     request_max_concurrency: Option<u64>,
     request_min_start_interval_ms: Option<u64>,
+    codex_image_generation_enabled: bool,
+    codex_image_generation_max_concurrency: u64,
 }
 
 impl Default for CodexAccountSettings {
@@ -477,6 +481,9 @@ impl Default for CodexAccountSettings {
             proxy_config_id: None,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency:
+                llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
         }
     }
 }
@@ -500,6 +507,23 @@ impl PostgresControlRepository {
     ) -> anyhow::Result<Self> {
         let client = SqlxClient::connect(database_url).await?;
         llm_access_migrations::run_postgres_migrations(&client.pool).await?;
+        Self::from_sqlx_client(client, request_cache_config, proxy_scope)
+    }
+
+    /// Connect to the Postgres control plane without running migrations.
+    pub async fn connect_read_only(
+        database_url: &str,
+        request_cache_config: Option<RequestCacheConfig>,
+    ) -> anyhow::Result<Self> {
+        let client = SqlxClient::connect(database_url).await?;
+        Self::from_sqlx_client(client, request_cache_config, ProxyConfigScope::core())
+    }
+
+    fn from_sqlx_client(
+        client: SqlxClient,
+        request_cache_config: Option<RequestCacheConfig>,
+        proxy_scope: ProxyConfigScope,
+    ) -> anyhow::Result<Self> {
         let request_cache = request_cache_config.map(RequestCache::new).transpose()?;
         Ok(Self {
             client,
diff --git a/crates/llm-access-store/src/postgres/cache.rs b/crates/llm-access-store/src/postgres/cache.rs
index 02f36cd2..48def5d9 100644
--- a/crates/llm-access-store/src/postgres/cache.rs
+++ b/crates/llm-access-store/src/postgres/cache.rs
@@ -446,6 +446,7 @@ impl PostgresControlRepository {
             codex_strict_session_rejection_enabled: bundle
                 .route
                 .codex_strict_session_rejection_enabled,
+            codex_image_generation_enabled: bundle.route.codex_image_generation_enabled,
             codex_weight_free: runtime_config.codex_weight_free,
             codex_weight_plus: runtime_config.codex_weight_plus,
             codex_weight_pro5x: runtime_config.codex_weight_pro5x,
@@ -580,6 +581,9 @@ impl PostgresControlRepository {
                         route_weight_tier: settings.route_weight_tier,
                         request_max_concurrency: settings.request_max_concurrency,
                         request_min_start_interval_ms: settings.request_min_start_interval_ms,
+                        codex_image_generation_enabled: settings.codex_image_generation_enabled,
+                        codex_image_generation_max_concurrency: settings
+                            .codex_image_generation_max_concurrency,
                         last_refresh_at_ms: row.last_refresh_at_ms,
                         last_error: row.last_error,
                         access_token: row.access_token,
@@ -641,6 +645,9 @@ impl PostgresControlRepository {
                 route_weight_tier: settings.route_weight_tier,
                 request_max_concurrency: settings.request_max_concurrency,
                 request_min_start_interval_ms: settings.request_min_start_interval_ms,
+                codex_image_generation_enabled: settings.codex_image_generation_enabled,
+                codex_image_generation_max_concurrency: settings
+                    .codex_image_generation_max_concurrency,
                 last_refresh_at_ms: row.last_refresh_at_ms,
                 last_error: row.last_error,
                 access_token: row.access_token,
diff --git a/crates/llm-access-store/src/postgres/codex_account.rs b/crates/llm-access-store/src/postgres/codex_account.rs
index 80543aa1..02aff39a 100644
--- a/crates/llm-access-store/src/postgres/codex_account.rs
+++ b/crates/llm-access-store/src/postgres/codex_account.rs
@@ -90,6 +90,23 @@ impl PostgresControlRepository {
                         THEN (settings_json ->> 'request_min_start_interval_ms')::bigint
                         ELSE NULL
                     END,
+                    COALESCE(
+                        CASE
+                            WHEN jsonb_typeof(settings_json -> 'codex_image_generation_enabled')
+                                = 'boolean'
+                            THEN (settings_json ->> 'codex_image_generation_enabled')::boolean
+                        END,
+                        false
+                    ),
+                    COALESCE(
+                        CASE
+                            WHEN jsonb_typeof(settings_json -> \
+                 'codex_image_generation_max_concurrency') = 'number'
+                            THEN (settings_json ->> \
+                 'codex_image_generation_max_concurrency')::bigint
+                        END,
+                        3
+                    ),
                     last_refresh_at_ms,
                     last_error,
                     COALESCE(
@@ -217,6 +234,23 @@ impl PostgresControlRepository {
                         THEN (settings_json ->> 'request_min_start_interval_ms')::bigint
                         ELSE NULL
                     END,
+                    COALESCE(
+                        CASE
+                            WHEN jsonb_typeof(settings_json -> 'codex_image_generation_enabled')
+                                = 'boolean'
+                            THEN (settings_json ->> 'codex_image_generation_enabled')::boolean
+                        END,
+                        false
+                    ),
+                    COALESCE(
+                        CASE
+                            WHEN jsonb_typeof(settings_json -> \
+                 'codex_image_generation_max_concurrency') = 'number'
+                            THEN (settings_json ->> \
+                 'codex_image_generation_max_concurrency')::bigint
+                        END,
+                        3
+                    ),
                     last_refresh_at_ms,
                     last_error,
                     COALESCE(
@@ -332,6 +366,23 @@ impl PostgresControlRepository {
                         THEN (a.settings_json ->> 'request_min_start_interval_ms')::bigint
                         ELSE NULL
                     END AS request_min_start_interval_ms,
+                    COALESCE(
+                        CASE
+                            WHEN jsonb_typeof(a.settings_json -> 'codex_image_generation_enabled')
+                                = 'boolean'
+                            THEN (a.settings_json ->> 'codex_image_generation_enabled')::boolean
+                        END,
+                        false
+                    ) AS codex_image_generation_enabled,
+                    COALESCE(
+                        CASE
+                            WHEN jsonb_typeof(a.settings_json -> \
+                        'codex_image_generation_max_concurrency') = 'number'
+                            THEN (a.settings_json ->> \
+                        'codex_image_generation_max_concurrency')::bigint
+                        END,
+                        3
+                    ) AS codex_image_generation_max_concurrency,
                     a.last_refresh_at_ms,
                     a.last_error,
                     COALESCE(
@@ -427,6 +478,8 @@ impl PostgresControlRepository {
                 proxy_config_id,
                 request_max_concurrency,
                 request_min_start_interval_ms,
+                codex_image_generation_enabled,
+                codex_image_generation_max_concurrency,
                 last_refresh_at_ms,
                 last_error,
                 access_token,
@@ -547,6 +600,10 @@ impl PostgresControlRepository {
             request_min_start_interval_ms: row
                 .request_min_start_interval_ms
                 .and_then(non_negative_i64_to_u64),
+            codex_image_generation_enabled: row.codex_image_generation_enabled,
+            codex_image_generation_max_concurrency: row
+                .codex_image_generation_max_concurrency
+                .max(1) as u64,
         };
         let (effective_proxy_source, effective_proxy_url, effective_proxy_config_name) =
             self.resolve_codex_account_proxy_view_with_context(&settings, context);
@@ -566,6 +623,8 @@ impl PostgresControlRepository {
             auto_refresh_enabled: settings.auth_refresh_enabled,
             request_max_concurrency: settings.request_max_concurrency,
             request_min_start_interval_ms: settings.request_min_start_interval_ms,
+            codex_image_generation_enabled: settings.codex_image_generation_enabled,
+            codex_image_generation_max_concurrency: settings.codex_image_generation_max_concurrency,
             proxy_mode: settings.proxy_mode,
             proxy_config_id: settings.proxy_config_id,
             effective_proxy_source,
@@ -606,6 +665,8 @@ impl PostgresControlRepository {
             auto_refresh_enabled: settings.auth_refresh_enabled,
             request_max_concurrency: settings.request_max_concurrency,
             request_min_start_interval_ms: settings.request_min_start_interval_ms,
+            codex_image_generation_enabled: settings.codex_image_generation_enabled,
+            codex_image_generation_max_concurrency: settings.codex_image_generation_max_concurrency,
             proxy_mode: settings.proxy_mode,
             proxy_config_id: settings.proxy_config_id,
             effective_proxy_source,
@@ -850,6 +911,12 @@ impl AdminCodexAccountStore for PostgresControlRepository {
         if let Some(value) = patch.request_min_start_interval_ms {
             settings.request_min_start_interval_ms = value;
         }
+        if let Some(value) = patch.codex_image_generation_enabled {
+            settings.codex_image_generation_enabled = value;
+        }
+        if let Some(value) = patch.codex_image_generation_max_concurrency {
+            settings.codex_image_generation_max_concurrency = value;
+        }
         record.settings_json =
             serde_json::to_string(&settings).context("serialize postgres codex settings")?;
         record.updated_at_ms = patch.updated_at_ms;
@@ -950,10 +1017,14 @@ impl AdminCodexAccountStore for PostgresControlRepository {
             auth_refresh_enabled: settings.auth_refresh_enabled,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
             account_request_max_concurrency: settings.request_max_concurrency,
             account_request_min_start_interval_ms: settings.request_min_start_interval_ms,
+            account_codex_image_generation_enabled: settings.codex_image_generation_enabled,
+            account_codex_image_generation_max_concurrency: settings
+                .codex_image_generation_max_concurrency,
             cached_error_message,
             proxy,
         }))
diff --git a/crates/llm-access-store/src/postgres/decode.rs b/crates/llm-access-store/src/postgres/decode.rs
index db234f37..54bde2c0 100644
--- a/crates/llm-access-store/src/postgres/decode.rs
+++ b/crates/llm-access-store/src/postgres/decode.rs
@@ -89,7 +89,7 @@ pub fn decode_runtime_config_row(row: PgRow) -> anyhow::Result<RuntimeConfigReco
 
 fn decode_key_bundle(row: &PgRow) -> anyhow::Result<KeyBundle> {
     let key_id: String = row.get(0);
-    let credit_total_raw: String = row.get(31);
+    let credit_total_raw: String = row.get(32);
     let credit_total = credit_total_raw
         .parse::<f64>()
         .with_context(|| format!("parse key rollup credit_total `{credit_total_raw}`"))?;
@@ -121,11 +121,12 @@ fn decode_key_bundle(row: &PgRow) -> anyhow::Result<KeyBundle> {
             request_min_start_interval_ms: row.get(17),
             codex_fast_enabled: row.get::<_, Option<bool>>(18).unwrap_or(true),
             codex_strict_session_rejection_enabled: row.get::<_, Option<bool>>(19).unwrap_or(false),
-            kiro_request_validation_enabled: row.get::<_, Option<bool>>(20).unwrap_or(false),
-            kiro_cache_estimation_enabled: row.get::<_, Option<bool>>(21).unwrap_or(false),
-            kiro_zero_cache_debug_enabled: row.get::<_, Option<bool>>(22).unwrap_or(false),
-            kiro_full_request_logging_enabled: row.get::<_, Option<bool>>(23).unwrap_or(false),
-            kiro_remote_media_resolution_enabled: row.get::<_, Option<bool>>(24).unwrap_or(false),
+            codex_image_generation_enabled: row.get::<_, Option<bool>>(20).unwrap_or(false),
+            kiro_request_validation_enabled: row.get::<_, Option<bool>>(21).unwrap_or(false),
+            kiro_cache_estimation_enabled: row.get::<_, Option<bool>>(22).unwrap_or(false),
+            kiro_zero_cache_debug_enabled: row.get::<_, Option<bool>>(23).unwrap_or(false),
+            kiro_full_request_logging_enabled: row.get::<_, Option<bool>>(24).unwrap_or(false),
+            kiro_remote_media_resolution_enabled: row.get::<_, Option<bool>>(25).unwrap_or(false),
             kiro_latency_routing_enabled: row
                 .get_optional_bool("kiro_latency_routing_enabled")
                 .unwrap_or(true),
@@ -135,19 +136,19 @@ fn decode_key_bundle(row: &PgRow) -> anyhow::Result<KeyBundle> {
             kiro_cctest_text_handling_enabled: row
                 .get_optional_bool("kiro_cctest_text_handling_enabled")
                 .unwrap_or(false),
-            kiro_cache_policy_override_json: row.get(25),
-            kiro_billable_model_multipliers_override_json: row.get(26),
+            kiro_cache_policy_override_json: row.get(26),
+            kiro_billable_model_multipliers_override_json: row.get(27),
         },
         rollup: KeyUsageRollup {
             key_id,
-            input_uncached_tokens: row.get(27),
-            input_cached_tokens: row.get(28),
-            output_tokens: row.get(29),
-            billable_tokens: row.get(30),
+            input_uncached_tokens: row.get(28),
+            input_cached_tokens: row.get(29),
+            output_tokens: row.get(30),
+            billable_tokens: row.get(31),
             credit_total,
-            credit_missing_events: row.get(32),
-            last_used_at_ms: row.get(33),
-            updated_at_ms: row.get(34),
+            credit_missing_events: row.get(33),
+            last_used_at_ms: row.get(34),
+            updated_at_ms: row.get(35),
         },
     })
 }
@@ -193,6 +194,7 @@ pub fn admin_key_from_bundle(bundle: &KeyBundle) -> AdminKey {
             .and_then(non_negative_i64_to_u64),
         codex_fast_enabled: bundle.route.codex_fast_enabled,
         codex_strict_session_rejection_enabled: bundle.route.codex_strict_session_rejection_enabled,
+        codex_image_generation_enabled: bundle.route.codex_image_generation_enabled,
         kiro_request_validation_enabled: bundle.route.kiro_request_validation_enabled,
         kiro_cache_estimation_enabled: bundle.route.kiro_cache_estimation_enabled,
         kiro_zero_cache_debug_enabled: bundle.route.kiro_zero_cache_debug_enabled,
@@ -244,7 +246,7 @@ fn decode_kiro_candidate_credit_summary_row(
 pub fn decode_kiro_admin_key_row(row: PgRow) -> anyhow::Result<AdminKey> {
     let bundle = decode_key_bundle(&row)?;
     let mut key = admin_key_from_bundle(&bundle);
-    key.kiro_candidate_credit_summary = Some(decode_kiro_candidate_credit_summary_row(&row, 35));
+    key.kiro_candidate_credit_summary = Some(decode_kiro_candidate_credit_summary_row(&row, 36));
     Ok(key)
 }
 
@@ -346,15 +348,17 @@ pub fn decode_codex_admin_account_list_row(row: PgRow) -> CodexAdminAccountListR
         proxy_config_id: row.get(7),
         request_max_concurrency: row.get(8),
         request_min_start_interval_ms: row.get(9),
-        last_refresh_at_ms: row.get(10),
-        last_error: row.get(11),
-        access_token: row.get(12),
-        plan_type: row.get(13),
-        primary_remaining_percent: row.get(14),
-        secondary_remaining_percent: row.get(15),
-        last_usage_checked_at_ms: row.get(16),
-        last_usage_success_at_ms: row.get(17),
-        usage_error_message: row.get(18),
+        codex_image_generation_enabled: row.get(10),
+        codex_image_generation_max_concurrency: row.get(11),
+        last_refresh_at_ms: row.get(12),
+        last_error: row.get(13),
+        access_token: row.get(14),
+        plan_type: row.get(15),
+        primary_remaining_percent: row.get(16),
+        secondary_remaining_percent: row.get(17),
+        last_usage_checked_at_ms: row.get(18),
+        last_usage_success_at_ms: row.get(19),
+        usage_error_message: row.get(20),
     }
 }
 
diff --git a/crates/llm-access-store/src/postgres/keys.rs b/crates/llm-access-store/src/postgres/keys.rs
index 46d89b6b..750fb5c7 100644
--- a/crates/llm-access-store/src/postgres/keys.rs
+++ b/crates/llm-access-store/src/postgres/keys.rs
@@ -90,6 +90,7 @@ impl PostgresControlRepository {
                     r.account_group_id, r.model_name_map_json::text,
                     r.request_max_concurrency, r.request_min_start_interval_ms,
                     r.codex_fast_enabled, r.codex_strict_session_rejection_enabled,
+                    r.codex_image_generation_enabled,
                     r.kiro_request_validation_enabled,
                     r.kiro_cache_estimation_enabled,
                     r.kiro_zero_cache_debug_enabled, r.kiro_full_request_logging_enabled,
@@ -134,6 +135,7 @@ impl PostgresControlRepository {
                     r.account_group_id, r.model_name_map_json::text,
                     r.request_max_concurrency, r.request_min_start_interval_ms,
                     r.codex_fast_enabled, r.codex_strict_session_rejection_enabled,
+                    r.codex_image_generation_enabled,
                     r.kiro_request_validation_enabled,
                     r.kiro_cache_estimation_enabled,
                     r.kiro_zero_cache_debug_enabled, r.kiro_full_request_logging_enabled,
@@ -250,6 +252,7 @@ impl PostgresControlRepository {
                     r.account_group_id, r.model_name_map_json::text,
                     r.request_max_concurrency, r.request_min_start_interval_ms,
                     r.codex_fast_enabled, r.codex_strict_session_rejection_enabled,
+                    r.codex_image_generation_enabled,
                     r.kiro_request_validation_enabled,
                     r.kiro_cache_estimation_enabled,
                     r.kiro_zero_cache_debug_enabled, r.kiro_full_request_logging_enabled,
@@ -320,6 +323,7 @@ impl PostgresControlRepository {
                         r.account_group_id, r.model_name_map_json,
                         r.request_max_concurrency, r.request_min_start_interval_ms,
                         r.codex_fast_enabled, r.codex_strict_session_rejection_enabled,
+                        r.codex_image_generation_enabled,
                         r.kiro_request_validation_enabled,
                         r.kiro_cache_estimation_enabled,
                         r.kiro_zero_cache_debug_enabled, r.kiro_full_request_logging_enabled,
@@ -499,6 +503,7 @@ impl PostgresControlRepository {
                     page_keys.request_max_concurrency, page_keys.request_min_start_interval_ms,
                     page_keys.codex_fast_enabled,
                     page_keys.codex_strict_session_rejection_enabled,
+                    page_keys.codex_image_generation_enabled,
                     page_keys.kiro_request_validation_enabled,
                     page_keys.kiro_cache_estimation_enabled,
                     page_keys.kiro_zero_cache_debug_enabled,
@@ -565,6 +570,7 @@ impl PostgresControlRepository {
                     r.account_group_id, r.model_name_map_json::text,
                     r.request_max_concurrency, r.request_min_start_interval_ms,
                     r.codex_fast_enabled, r.codex_strict_session_rejection_enabled,
+                    r.codex_image_generation_enabled,
                     r.kiro_request_validation_enabled,
                     r.kiro_cache_estimation_enabled,
                     r.kiro_zero_cache_debug_enabled, r.kiro_full_request_logging_enabled,
@@ -647,6 +653,7 @@ impl PostgresControlRepository {
                     request_max_concurrency,
                     request_min_start_interval_ms, codex_fast_enabled,
                     codex_strict_session_rejection_enabled,
+                    codex_image_generation_enabled,
                     kiro_request_validation_enabled, kiro_cache_estimation_enabled,
                     kiro_zero_cache_debug_enabled, kiro_full_request_logging_enabled,
                     kiro_remote_media_resolution_enabled, kiro_latency_routing_enabled,
@@ -656,7 +663,7 @@ impl PostgresControlRepository {
                     kiro_billable_model_multipliers_override_json
                  ) VALUES (
                     $1, $2, $3, $4::jsonb, $5, $6, $7::jsonb, $8, $9, $10, $11, $12,
-                    $13, $14, $15, $16, $17, $18, $19, $20::jsonb, $21::jsonb
+                    $13, $14, $15, $16, $17, $18, $19, $20, $21::jsonb, $22::jsonb
                  )
                  ON CONFLICT(key_id) DO UPDATE SET
                     route_strategy = EXCLUDED.route_strategy,
@@ -670,6 +677,8 @@ impl PostgresControlRepository {
                     codex_fast_enabled = EXCLUDED.codex_fast_enabled,
                     codex_strict_session_rejection_enabled =
                         EXCLUDED.codex_strict_session_rejection_enabled,
+                    codex_image_generation_enabled =
+                        EXCLUDED.codex_image_generation_enabled,
                     kiro_request_validation_enabled = EXCLUDED.kiro_request_validation_enabled,
                     kiro_cache_estimation_enabled = EXCLUDED.kiro_cache_estimation_enabled,
                     kiro_zero_cache_debug_enabled = EXCLUDED.kiro_zero_cache_debug_enabled,
@@ -699,6 +708,7 @@ impl PostgresControlRepository {
                     &route.request_min_start_interval_ms,
                     &route.codex_fast_enabled,
                     &route.codex_strict_session_rejection_enabled,
+                    &route.codex_image_generation_enabled,
                     &route.kiro_request_validation_enabled,
                     &route.kiro_cache_estimation_enabled,
                     &route.kiro_zero_cache_debug_enabled,
@@ -854,6 +864,7 @@ impl AdminKeyStore for PostgresControlRepository {
                 r.account_group_id, r.model_name_map_json::text,
                 r.request_max_concurrency, r.request_min_start_interval_ms,
                 r.codex_fast_enabled, r.codex_strict_session_rejection_enabled,
+                r.codex_image_generation_enabled,
                 r.kiro_request_validation_enabled,
                 r.kiro_cache_estimation_enabled,
                 r.kiro_zero_cache_debug_enabled, r.kiro_full_request_logging_enabled,
@@ -951,6 +962,7 @@ impl AdminKeyStore for PostgresControlRepository {
                 .map(|value| value as i64),
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: false,
             kiro_request_validation_enabled: true,
             kiro_cache_estimation_enabled: true,
             kiro_zero_cache_debug_enabled: false,
@@ -1039,6 +1051,9 @@ impl AdminKeyStore for PostgresControlRepository {
         if let Some(value) = patch.codex_strict_session_rejection_enabled {
             bundle.route.codex_strict_session_rejection_enabled = value;
         }
+        if let Some(value) = patch.codex_image_generation_enabled {
+            bundle.route.codex_image_generation_enabled = value;
+        }
         if let Some(value) = patch.kiro_request_validation_enabled {
             bundle.route.kiro_request_validation_enabled = value;
         }
diff --git a/crates/llm-access-store/src/postgres/routes.rs b/crates/llm-access-store/src/postgres/routes.rs
index f8cd6ed4..8cad1aea 100644
--- a/crates/llm-access-store/src/postgres/routes.rs
+++ b/crates/llm-access-store/src/postgres/routes.rs
@@ -505,10 +505,14 @@ impl ProviderRouteStore for PostgresControlRepository {
                 codex_fast_enabled: snapshot.codex_fast_enabled,
                 codex_strict_session_rejection_enabled: snapshot
                     .codex_strict_session_rejection_enabled,
+                codex_image_generation_enabled: snapshot.codex_image_generation_enabled,
                 request_max_concurrency: snapshot.request_max_concurrency,
                 request_min_start_interval_ms: snapshot.request_min_start_interval_ms,
                 account_request_max_concurrency: view.request_max_concurrency,
                 account_request_min_start_interval_ms: view.request_min_start_interval_ms,
+                account_codex_image_generation_enabled: view.codex_image_generation_enabled,
+                account_codex_image_generation_max_concurrency: view
+                    .codex_image_generation_max_concurrency,
                 cached_error_message,
                 proxy: proxy_from_cached_option(view.proxy),
             });
@@ -578,10 +582,14 @@ impl ProviderRouteStore for PostgresControlRepository {
             auth_refresh_enabled: view.auth_refresh_enabled,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
             account_request_max_concurrency: view.request_max_concurrency,
             account_request_min_start_interval_ms: view.request_min_start_interval_ms,
+            account_codex_image_generation_enabled: view.codex_image_generation_enabled,
+            account_codex_image_generation_max_concurrency: view
+                .codex_image_generation_max_concurrency,
             cached_error_message,
             proxy: proxy_from_cached_option(view.proxy),
         }))
diff --git a/crates/llm-access-store/src/records.rs b/crates/llm-access-store/src/records.rs
index a2c9d556..56f6cd7c 100644
--- a/crates/llm-access-store/src/records.rs
+++ b/crates/llm-access-store/src/records.rs
@@ -66,6 +66,8 @@ pub struct KeyRouteConfig {
     pub codex_fast_enabled: bool,
     /// Whether repeated fatal Codex session errors are rejected early.
     pub codex_strict_session_rejection_enabled: bool,
+    /// Whether Codex image generation/edit requests are enabled for this key.
+    pub codex_image_generation_enabled: bool,
     /// Whether Kiro public request validation is enabled.
     pub kiro_request_validation_enabled: bool,
     /// Whether Kiro cache estimation is enabled.
diff --git a/crates/llm-access-store/src/request_cache.rs b/crates/llm-access-store/src/request_cache.rs
index 8ae15538..a4ffe439 100644
--- a/crates/llm-access-store/src/request_cache.rs
+++ b/crates/llm-access-store/src/request_cache.rs
@@ -6,7 +6,9 @@ use llm_access_core::store::{
     CodexRateLimitStatus, ProviderProxyConfig, DEFAULT_KIRO_COMPACT_TRIGGER_TOKENS,
     DEFAULT_KIRO_CONTEXT_USAGE_MIN_REQUEST_TOKENS,
 };
-use redis::{AsyncCommands, Commands};
+use redis::AsyncCommands;
+#[cfg(feature = "duckdb-runtime")]
+use redis::Commands;
 use serde::{de::DeserializeOwned, Deserialize, Serialize};
 use sha2::{Digest, Sha256};
 
@@ -21,7 +23,9 @@ const ACCOUNT_PRINCIPAL_TTL: Duration = Duration::from_secs(4 * 60 * 60);
 const CODEX_STATUS_TTL: Duration = Duration::from_secs(4 * 60 * 60);
 const PROXY_METADATA_TTL: Duration = Duration::from_secs(6 * 60 * 60);
 const USAGE_PROXY_ATTRIBUTION_TTL: Duration = Duration::from_secs(30 * 60);
+#[cfg(feature = "duckdb-runtime")]
 const USAGE_CATALOG_LOOKUP_TTL: Duration = Duration::from_secs(15 * 60);
+#[cfg(feature = "duckdb-runtime")]
 const USAGE_CATALOG_EVENT_LOCATOR_TTL: Duration = Duration::from_secs(30 * 60);
 const NEGATIVE_AUTH_TTL: Duration = Duration::from_secs(5 * 60);
 
@@ -41,6 +45,10 @@ fn default_kiro_pool_strategy() -> String {
     llm_access_core::store::default_kiro_pool_strategy()
 }
 
+const fn default_codex_image_generation_max_concurrency() -> u64 {
+    llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY
+}
+
 /// Shared Valkey configuration for the request-path cache layer.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RequestCacheConfig {
@@ -127,6 +135,8 @@ pub(crate) struct CachedCodexRequestSnapshot {
     pub codex_fast_enabled: bool,
     #[serde(default)]
     pub codex_strict_session_rejection_enabled: bool,
+    #[serde(default)]
+    pub codex_image_generation_enabled: bool,
     pub codex_weight_free: i64,
     pub codex_weight_plus: i64,
     pub codex_weight_pro5x: i64,
@@ -216,6 +226,10 @@ pub(crate) struct CachedCodexAccountView {
     pub route_weight_tier: Option<String>,
     pub request_max_concurrency: Option<u64>,
     pub request_min_start_interval_ms: Option<u64>,
+    #[serde(default)]
+    pub codex_image_generation_enabled: bool,
+    #[serde(default = "default_codex_image_generation_max_concurrency")]
+    pub codex_image_generation_max_concurrency: u64,
     pub last_refresh_at_ms: Option<i64>,
     pub last_error: Option<String>,
     pub access_token: Option<String>,
@@ -258,7 +272,68 @@ pub(crate) struct CachedAccountAuth {
     pub auth_json: String,
 }
 
+#[cfg(test)]
+mod codex_image_cache_tests {
+    use serde_json::json;
+
+    use super::{CachedCodexAccountView, CachedCodexRequestSnapshot};
+
+    #[test]
+    fn legacy_codex_request_snapshot_defaults_image_generation_disabled() {
+        let snapshot: CachedCodexRequestSnapshot = serde_json::from_value(json!({
+            "key": {
+                "key_id": "key-1",
+                "key_name": "Codex",
+                "provider_type": "codex",
+                "protocol_family": "openai",
+                "status": "active",
+                "quota_billable_limit": 1000,
+                "billable_tokens_used": 0
+            },
+            "generation": 7,
+            "route_strategy": "auto",
+            "account_group_id_at_event": null,
+            "selected_account_names": ["acc-a"],
+            "use_all_active_accounts": false,
+            "request_max_concurrency": null,
+            "request_min_start_interval_ms": null,
+            "codex_fast_enabled": true,
+            "codex_strict_session_rejection_enabled": false,
+            "codex_weight_free": 1,
+            "codex_weight_plus": 2,
+            "codex_weight_pro5x": 5,
+            "codex_weight_pro20x": 20
+        }))
+        .expect("legacy snapshot must decode");
+
+        assert!(!snapshot.codex_image_generation_enabled);
+    }
+
+    #[test]
+    fn legacy_codex_account_view_defaults_image_settings_closed() {
+        let view: CachedCodexAccountView = serde_json::from_value(json!({
+            "generation": 1,
+            "account_name": "acc-a",
+            "status": "active",
+            "map_gpt53_codex_to_spark": false,
+            "auth_refresh_enabled": true,
+            "route_weight_tier": null,
+            "request_max_concurrency": null,
+            "request_min_start_interval_ms": null,
+            "last_refresh_at_ms": null,
+            "last_error": null,
+            "access_token": null,
+            "proxy": null
+        }))
+        .expect("legacy account view must decode");
+
+        assert!(!view.codex_image_generation_enabled);
+        assert_eq!(view.codex_image_generation_max_concurrency, 3);
+    }
+}
+
 impl RequestCache {
+    #[cfg(feature = "duckdb-runtime")]
     const USAGE_CATALOG_CACHE_NAMESPACE: &str = "usage:catalog:v2";
 
     pub(crate) fn new(config: RequestCacheConfig) -> anyhow::Result<Self> {
@@ -329,14 +404,17 @@ impl RequestCache {
         format!("{}:usage:proxy:scope:{scope}:{provider}:{account_name}", self.key_prefix)
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_generation_key(&self) -> String {
         format!("{}:{}:gen", self.key_prefix, Self::USAGE_CATALOG_CACHE_NAMESPACE)
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_rollups_key(&self) -> String {
         format!("{}:{}:rollups", self.key_prefix, Self::USAGE_CATALOG_CACHE_NAMESPACE)
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_filtered_segments_key(&self, query_fingerprint: &str) -> String {
         format!(
             "{}:{}:segments:filtered:{query_fingerprint}",
@@ -345,10 +423,12 @@ impl RequestCache {
         )
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_event_locator_key(&self, event_id: &str) -> String {
         format!("{}:{}:event:{event_id}", self.key_prefix, Self::USAGE_CATALOG_CACHE_NAMESPACE)
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_filter_options_key(&self, query_fingerprint: &str) -> String {
         format!(
             "{}:{}:filter-options:{query_fingerprint}",
@@ -432,6 +512,7 @@ impl RequestCache {
         )
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_rollups_ttl(&self) -> Duration {
         deterministic_jitter_ttl(
             &self.usage_catalog_rollups_key(),
@@ -455,6 +536,7 @@ impl RequestCache {
         )
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_filtered_segments_ttl(&self, query_fingerprint: &str) -> Duration {
         deterministic_jitter_ttl(
             &self.usage_catalog_filtered_segments_key(query_fingerprint),
@@ -464,6 +546,7 @@ impl RequestCache {
         )
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_event_locator_ttl(&self, event_id: &str) -> Duration {
         deterministic_jitter_ttl(
             &self.usage_catalog_event_locator_key(event_id),
@@ -473,6 +556,7 @@ impl RequestCache {
         )
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn usage_catalog_filter_options_ttl(&self, query_fingerprint: &str) -> Duration {
         deterministic_jitter_ttl(
             &self.usage_catalog_filter_options_key(query_fingerprint),
@@ -586,6 +670,7 @@ impl RequestCache {
             .with_context(|| format!("redis INCR `{key}`"))
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn get_json_blocking<T>(&self, key: &str) -> anyhow::Result<Option<T>>
     where
         T: DeserializeOwned,
@@ -599,6 +684,7 @@ impl RequestCache {
             .transpose()
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn set_json_blocking<T>(
         &self,
         key: &str,
@@ -621,6 +707,7 @@ impl RequestCache {
         Ok(())
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn get_i64_blocking(&self, key: &str) -> anyhow::Result<Option<i64>> {
         let mut conn = self.connection_blocking()?;
         let value: Option<i64> = conn
@@ -629,6 +716,7 @@ impl RequestCache {
         Ok(value)
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     pub(crate) fn incr_blocking(&self, key: &str) -> anyhow::Result<i64> {
         let mut conn = self.connection_blocking()?;
         conn.incr(key, 1)
@@ -642,6 +730,7 @@ impl RequestCache {
             .context("connect request cache redis")
     }
 
+    #[cfg(feature = "duckdb-runtime")]
     fn connection_blocking(&self) -> anyhow::Result<redis::Connection> {
         self.client
             .get_connection()
@@ -729,6 +818,7 @@ mod tests {
             request_min_start_interval_ms: Some(50),
             codex_fast_enabled: false,
             codex_strict_session_rejection_enabled: true,
+            codex_image_generation_enabled: false,
             codex_weight_free: 1,
             codex_weight_plus: 2,
             codex_weight_pro5x: 3,
diff --git a/crates/llm-access/src/admin.rs b/crates/llm-access/src/admin.rs
index 2d36b85f..4fe70c7a 100644
--- a/crates/llm-access/src/admin.rs
+++ b/crates/llm-access/src/admin.rs
@@ -568,6 +568,8 @@ pub(crate) struct PatchLlmGatewayKeyRequest {
     #[serde(default)]
     codex_strict_session_rejection_enabled: Option<bool>,
     #[serde(default)]
+    codex_image_generation_enabled: Option<bool>,
+    #[serde(default)]
     kiro_request_validation_enabled: Option<bool>,
     #[serde(default)]
     kiro_cache_estimation_enabled: Option<bool>,
@@ -700,6 +702,10 @@ pub(crate) struct PatchLlmGatewayAccountRequest {
     request_max_concurrency_unlimited: bool,
     #[serde(default)]
     request_min_start_interval_ms_unlimited: bool,
+    #[serde(default)]
+    codex_image_generation_enabled: Option<bool>,
+    #[serde(default)]
+    codex_image_generation_max_concurrency: Option<u64>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -5366,10 +5372,14 @@ fn codex_validation_route(
         auth_refresh_enabled: true,
         codex_fast_enabled: true,
         codex_strict_session_rejection_enabled: false,
+        codex_image_generation_enabled: true,
         request_max_concurrency: None,
         request_min_start_interval_ms: None,
         account_request_max_concurrency: None,
         account_request_min_start_interval_ms: None,
+        account_codex_image_generation_enabled: true,
+        account_codex_image_generation_max_concurrency:
+            core_store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
         cached_error_message: None,
         proxy: Some(proxy),
     }
@@ -6214,6 +6224,7 @@ fn normalize_key_patch(
         request_min_start_interval_ms,
         codex_fast_enabled: request.codex_fast_enabled,
         codex_strict_session_rejection_enabled: request.codex_strict_session_rejection_enabled,
+        codex_image_generation_enabled: request.codex_image_generation_enabled,
         kiro_request_validation_enabled: request.kiro_request_validation_enabled,
         kiro_cache_estimation_enabled: request.kiro_cache_estimation_enabled,
         kiro_zero_cache_debug_enabled: request.kiro_zero_cache_debug_enabled,
@@ -6239,6 +6250,7 @@ fn normalize_kiro_key_patch(
     request.request_min_start_interval_ms_unlimited = false;
     request.codex_fast_enabled = None;
     request.codex_strict_session_rejection_enabled = None;
+    request.codex_image_generation_enabled = None;
     normalize_key_patch(request)
 }
 
@@ -6603,6 +6615,9 @@ fn normalize_account_patch(
         request_max_concurrency.flatten(),
         request_min_start_interval_ms.flatten(),
     )?;
+    if let Some(value) = request.codex_image_generation_max_concurrency {
+        validate_codex_image_generation_max_concurrency(value)?;
+    }
     Ok(AdminCodexAccountPatch {
         status,
         map_gpt53_codex_to_spark: request.map_gpt53_codex_to_spark,
@@ -6612,6 +6627,8 @@ fn normalize_account_patch(
         proxy_config_id,
         request_max_concurrency,
         request_min_start_interval_ms,
+        codex_image_generation_enabled: request.codex_image_generation_enabled,
+        codex_image_generation_max_concurrency: request.codex_image_generation_max_concurrency,
         updated_at_ms: now_ms(),
     })
 }
@@ -6977,6 +6994,13 @@ fn validate_codex_request_limit_inputs(
     Ok(())
 }
 
+fn validate_codex_image_generation_max_concurrency(value: u64) -> Result<(), AdminHttpError> {
+    if value == 0 || value > MAX_CODEX_KEY_REQUEST_MAX_CONCURRENCY {
+        return Err(bad_request("codex_image_generation_max_concurrency is out of range"));
+    }
+    Ok(())
+}
+
 fn validate_i64_backed_u64(field: &str, value: u64) -> Result<(), AdminHttpError> {
     if value <= i64::MAX as u64 {
         Ok(())
@@ -7318,6 +7342,7 @@ mod tests {
             request_min_start_interval_ms_unlimited: false,
             codex_fast_enabled: None,
             codex_strict_session_rejection_enabled: None,
+            codex_image_generation_enabled: None,
             kiro_request_validation_enabled: None,
             kiro_cache_estimation_enabled: None,
             kiro_zero_cache_debug_enabled: None,
@@ -7360,6 +7385,7 @@ mod tests {
             request_min_start_interval_ms: None,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: false,
             kiro_request_validation_enabled: true,
             kiro_cache_estimation_enabled: true,
             kiro_zero_cache_debug_enabled: false,
@@ -7623,6 +7649,8 @@ mod tests {
             request_min_start_interval_ms: None,
             request_max_concurrency_unlimited: false,
             request_min_start_interval_ms_unlimited: false,
+            codex_image_generation_enabled: None,
+            codex_image_generation_max_concurrency: None,
         })
         .expect("auto refresh toggle should be accepted");
 
@@ -8063,6 +8091,9 @@ mod tests {
             auto_refresh_enabled: true,
             request_max_concurrency: Some(3),
             request_min_start_interval_ms: Some(1000),
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency:
+                core_store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
@@ -8123,6 +8154,9 @@ mod tests {
             auto_refresh_enabled: true,
             request_max_concurrency: Some(3),
             request_min_start_interval_ms: Some(1000),
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency:
+                core_store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
@@ -8179,6 +8213,9 @@ mod tests {
             auto_refresh_enabled: true,
             request_max_concurrency: Some(3),
             request_min_start_interval_ms: Some(1000),
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency:
+                core_store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
diff --git a/crates/llm-access/src/codex_refresh.rs b/crates/llm-access/src/codex_refresh.rs
index ad4e042f..d2ee11a8 100644
--- a/crates/llm-access/src/codex_refresh.rs
+++ b/crates/llm-access/src/codex_refresh.rs
@@ -660,10 +660,14 @@ mod tests {
             auth_refresh_enabled: true,
             codex_fast_enabled: true,
             codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
             account_request_max_concurrency: None,
             account_request_min_start_interval_ms: None,
+            account_codex_image_generation_enabled: true,
+            account_codex_image_generation_max_concurrency:
+                llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
             cached_error_message: None,
             proxy: None,
         }
diff --git a/crates/llm-access/src/codex_status.rs b/crates/llm-access/src/codex_status.rs
index 61f25102..cf37bac9 100644
--- a/crates/llm-access/src/codex_status.rs
+++ b/crates/llm-access/src/codex_status.rs
@@ -1650,6 +1650,9 @@ mod tests {
             auto_refresh_enabled: true,
             request_max_concurrency: None,
             request_min_start_interval_ms: None,
+            codex_image_generation_enabled: false,
+            codex_image_generation_max_concurrency:
+                llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
             proxy_mode: "inherit".to_string(),
             proxy_config_id: None,
             effective_proxy_source: "binding".to_string(),
diff --git a/crates/llm-access/src/provider/route_selection.rs b/crates/llm-access/src/provider/route_selection.rs
index e54184d9..feabcdcd 100644
--- a/crates/llm-access/src/provider/route_selection.rs
+++ b/crates/llm-access/src/provider/route_selection.rs
@@ -307,6 +307,9 @@ pub async fn hydrate_codex_route_for_dispatch(
     route.auth_refresh_enabled = loaded.auth_refresh_enabled;
     route.account_request_max_concurrency = loaded.account_request_max_concurrency;
     route.account_request_min_start_interval_ms = loaded.account_request_min_start_interval_ms;
+    route.account_codex_image_generation_enabled = loaded.account_codex_image_generation_enabled;
+    route.account_codex_image_generation_max_concurrency =
+        loaded.account_codex_image_generation_max_concurrency;
     route.cached_error_message = loaded.cached_error_message;
     route.proxy = loaded.proxy;
     Ok(route)
diff --git a/crates/llm-access/src/provider/tests.rs b/crates/llm-access/src/provider/tests.rs
index f533e83d..ac970fc9 100644
--- a/crates/llm-access/src/provider/tests.rs
+++ b/crates/llm-access/src/provider/tests.rs
@@ -1408,10 +1408,14 @@ fn codex_route_for_account(account_name: &str, access_token: &str) -> ProviderCo
         auth_refresh_enabled: true,
         codex_fast_enabled: true,
         codex_strict_session_rejection_enabled: false,
+        codex_image_generation_enabled: true,
         request_max_concurrency: None,
         request_min_start_interval_ms: None,
         account_request_max_concurrency: None,
         account_request_min_start_interval_ms: None,
+        account_codex_image_generation_enabled: true,
+        account_codex_image_generation_max_concurrency:
+            llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
         cached_error_message: None,
         proxy: None,
     }
@@ -8209,10 +8213,14 @@ async fn kiro_generate_uses_fixed_social_profile_arn_when_route_is_missing_it()
                 auth_refresh_enabled: true,
                 codex_fast_enabled: true,
                 codex_strict_session_rejection_enabled: false,
+                codex_image_generation_enabled: true,
                 request_max_concurrency: None,
                 request_min_start_interval_ms: None,
                 account_request_max_concurrency: None,
                 account_request_min_start_interval_ms: None,
+                account_codex_image_generation_enabled: true,
+                account_codex_image_generation_max_concurrency:
+                    llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
                 cached_error_message: None,
                 proxy: None,
             },
@@ -8276,10 +8284,14 @@ async fn kiro_generate_headers_include_runtime_middleware_for_external_idp_inter
                 auth_refresh_enabled: true,
                 codex_fast_enabled: true,
                 codex_strict_session_rejection_enabled: false,
+                codex_image_generation_enabled: true,
                 request_max_concurrency: None,
                 request_min_start_interval_ms: None,
                 account_request_max_concurrency: None,
                 account_request_min_start_interval_ms: None,
+                account_codex_image_generation_enabled: true,
+                account_codex_image_generation_max_concurrency:
+                    llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
                 cached_error_message: None,
                 proxy: None,
             },
@@ -8812,10 +8824,14 @@ async fn kiro_dispatch_applies_key_model_mapping_before_upstream_conversion() {
                 auth_refresh_enabled: true,
                 codex_fast_enabled: true,
                 codex_strict_session_rejection_enabled: false,
+                codex_image_generation_enabled: true,
                 request_max_concurrency: None,
                 request_min_start_interval_ms: None,
                 account_request_max_concurrency: None,
                 account_request_min_start_interval_ms: None,
+                account_codex_image_generation_enabled: true,
+                account_codex_image_generation_max_concurrency:
+                    llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY,
                 cached_error_message: None,
                 proxy: None,
             },
diff --git a/deployment-examples/caddy/llm-access-path-split.Caddyfile b/deployment-examples/caddy/llm-access-path-split.Caddyfile
index 5bd897c5..faa50ecb 100644
--- a/deployment-examples/caddy/llm-access-path-split.Caddyfile
+++ b/deployment-examples/caddy/llm-access-path-split.Caddyfile
@@ -5,6 +5,22 @@ ackingliu.top, www.ackingliu.top, staticflow.cc, www.staticflow.cc {
         @admin path /admin*
         respond @admin "forbidden" 403
 
+	@codex_image path /v1/images/generations /v1/images/edits /api/codex-gateway/images/generations /api/codex-gateway/images/edits /api/codex-gateway/v1/images/generations /api/codex-gateway/v1/images/edits /api/llm-gateway/v1/images/generations /api/llm-gateway/v1/images/edits
+	handle @codex_image {
+		reverse_proxy 127.0.0.1:19082 {
+			transport http {
+				dial_timeout 10s
+				response_header_timeout 15m
+				read_timeout 15m
+				write_timeout 15m
+			}
+			header_up X-Real-IP {remote_host}
+			header_up X-Forwarded-For {remote_host}
+			header_up X-Forwarded-Proto {scheme}
+			header_up X-Forwarded-Host {host}
+		}
+        }
+
 	@llm_access path /v1/* /cc/v1/* /api/llm-gateway/* /api/kiro-gateway/* /api/codex-gateway/* /api/llm-access/*
 	handle @llm_access {
 		reverse_proxy 127.0.0.1:19080 {
diff --git a/deployment-examples/systemd/llm-access-codex-image.service.template b/deployment-examples/systemd/llm-access-codex-image.service.template
new file mode 100644
index 00000000..d4b9bb4b
--- /dev/null
+++ b/deployment-examples/systemd/llm-access-codex-image.service.template
@@ -0,0 +1,33 @@
+[Unit]
+Description=StaticFlow Codex Image Gateway
+After=network-online.target mnt-llm\x2daccess.mount
+Wants=network-online.target
+RequiresMountsFor=/mnt/llm-access
+
+[Service]
+Type=simple
+User=ts_user
+Group=ts_user
+TimeoutStartSec=120
+EnvironmentFile=/etc/llm-access/llm-access.env
+Environment=STATICFLOW_LOG_DIR=/var/log/staticflow-runtime
+Environment=STATICFLOW_LOG_SERVICE=llm-access-codex-image
+Environment=STATICFLOW_LOG_STDOUT=0
+WorkingDirectory=/mnt/llm-access
+ExecStart=/usr/bin/bash -lc 'set -a; . /mnt/llm-access/config/neon.env; exec /usr/local/bin/llm-access-codex-image serve --bind 127.0.0.1:19082 --state-root /mnt/llm-access --postgres-control-database-url-env LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL --request-cache-url-env LLM_ACCESS_REQUEST_CACHE_URL --request-cache-key-prefix llma --image-log-dir /var/lib/staticflow/llm-access/codex-image-logs'
+Restart=always
+RestartSec=3
+NoNewPrivileges=true
+StateDirectory=staticflow/llm-access
+MemoryAccounting=yes
+MemoryHigh=768M
+MemoryMax=1024M
+MemorySwapMax=256M
+TasksMax=128
+OOMPolicy=kill
+# Do not add ProtectSystem/ReadWritePaths/PrivateTmp for this unit when
+# /mnt/llm-access is a JuiceFS FUSE mount with default_permissions. Those
+# systemd mount namespace features can fail before ExecStart with 226/NAMESPACE.
+
+[Install]
+WantedBy=multi-user.target
diff --git a/scripts/activate_llm_access_cloud_release.sh b/scripts/activate_llm_access_cloud_release.sh
index 23e7cc73..d797b659 100755
--- a/scripts/activate_llm_access_cloud_release.sh
+++ b/scripts/activate_llm_access_cloud_release.sh
@@ -5,27 +5,33 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 RELEASE_DIR="${LLM_ACCESS_RELEASE_DIR:-$SCRIPT_DIR}"
 SERVICE="${LLM_ACCESS_SERVICE:-llm-access.service}"
 WORKER_SERVICE="${LLM_ACCESS_USAGE_WORKER_SERVICE:-llm-access-usage-worker.service}"
+IMAGE_SERVICE="${LLM_ACCESS_CODEX_IMAGE_SERVICE:-llm-access-codex-image.service}"
 USAGE_MOUNT_SERVICE="${LLM_ACCESS_USAGE_MOUNT_SERVICE:-juicefs-llm-access-usage.service}"
 SERVICE_USER="${LLM_ACCESS_SERVICE_USER:-ts_user}"
 SERVICE_GROUP="${LLM_ACCESS_SERVICE_GROUP:-$SERVICE_USER}"
 ACTIVATE_TARGET="${LLM_ACCESS_ACTIVATE_TARGET:-both}"
 INSTALL_PATH="${LLM_ACCESS_INSTALL_PATH:-/usr/local/bin/llm-access}"
 WORKER_INSTALL_PATH="${LLM_ACCESS_USAGE_WORKER_INSTALL_PATH:-/usr/local/bin/llm-access-usage-worker}"
+IMAGE_INSTALL_PATH="${LLM_ACCESS_CODEX_IMAGE_INSTALL_PATH:-/usr/local/bin/llm-access-codex-image}"
 SERVICE_UNIT_INSTALL_PATH="${LLM_ACCESS_SERVICE_UNIT_INSTALL_PATH:-/etc/systemd/system/llm-access.service}"
 WORKER_SERVICE_UNIT_INSTALL_PATH="${LLM_ACCESS_USAGE_WORKER_SERVICE_UNIT_INSTALL_PATH:-/etc/systemd/system/llm-access-usage-worker.service}"
+IMAGE_SERVICE_UNIT_INSTALL_PATH="${LLM_ACCESS_CODEX_IMAGE_SERVICE_UNIT_INSTALL_PATH:-/etc/systemd/system/llm-access-codex-image.service}"
 USAGE_MOUNT_SERVICE_UNIT_INSTALL_PATH="${LLM_ACCESS_USAGE_MOUNT_SERVICE_UNIT_INSTALL_PATH:-/etc/systemd/system/juicefs-llm-access-usage.service}"
 BACKUP_DIR="${LLM_ACCESS_BACKUP_DIR:-/usr/local/bin/staticflow-backups}"
 HEALTH_URL="${LLM_ACCESS_HEALTH_URL:-http://127.0.0.1:19080/healthz}"
 WORKER_HEALTH_URL="${LLM_ACCESS_USAGE_WORKER_HEALTH_URL:-http://127.0.0.1:19081/admin/llm-access/usage-worker/status}"
+IMAGE_HEALTH_URL="${LLM_ACCESS_CODEX_IMAGE_HEALTH_URL:-http://127.0.0.1:19082/healthz}"
 VERSION_URL="${LLM_ACCESS_VERSION_URL:-http://127.0.0.1:19080/version}"
 JOURNAL_LINES="${JOURNAL_LINES:-80}"
 NEON_ENV_PATH="${LLM_ACCESS_CONTROL_DATABASE_URL_FILE:-/mnt/llm-access/config/neon.env}"
 STAGED_NEON_ENV="${LLM_ACCESS_STAGED_NEON_ENV:-$RELEASE_DIR/llm-access-neon.env.latest}"
 STAGED_BIN="${1:-$RELEASE_DIR/llm-access.latest}"
 STAGED_WORKER_BIN="${2:-$RELEASE_DIR/llm-access-usage-worker.latest}"
+STAGED_IMAGE_BIN="${LLM_ACCESS_STAGED_CODEX_IMAGE_BIN:-$RELEASE_DIR/llm-access-codex-image.latest}"
 MANIFEST="${LLM_ACCESS_RELEASE_MANIFEST:-$RELEASE_DIR/release.latest.env}"
 STAGED_SERVICE_UNIT="${LLM_ACCESS_STAGED_SERVICE_UNIT:-$RELEASE_DIR/llm-access.service.release}"
 STAGED_WORKER_SERVICE_UNIT="${LLM_ACCESS_STAGED_WORKER_SERVICE_UNIT:-$RELEASE_DIR/llm-access-usage-worker.service.release}"
+STAGED_IMAGE_SERVICE_UNIT="${LLM_ACCESS_STAGED_IMAGE_SERVICE_UNIT:-$RELEASE_DIR/llm-access-codex-image.service.release}"
 STAGED_USAGE_MOUNT_SERVICE_UNIT="${LLM_ACCESS_STAGED_USAGE_MOUNT_SERVICE_UNIT:-$RELEASE_DIR/juicefs-llm-access-usage.service.release}"
 
 log() {
@@ -184,10 +190,10 @@ for cmd in awk curl findmnt install sed seq sha256sum sudo systemctl; do
 done
 
 case "$ACTIVATE_TARGET" in
-  api|worker|both)
+  api|worker|image|both)
     ;;
   *)
-    fail "unsupported activation target: $ACTIVATE_TARGET (expected api, worker, or both)"
+    fail "unsupported activation target: $ACTIVATE_TARGET (expected api, worker, image, or both)"
     ;;
 esac
 
@@ -199,6 +205,10 @@ if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
   [[ -f "$STAGED_WORKER_BIN" ]] || fail "staged usage worker binary not found: $STAGED_WORKER_BIN"
   [[ -r "$STAGED_WORKER_BIN" ]] || fail "staged usage worker binary is not readable: $STAGED_WORKER_BIN"
 fi
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  [[ -f "$STAGED_IMAGE_BIN" ]] || fail "staged codex image binary not found: $STAGED_IMAGE_BIN"
+  [[ -r "$STAGED_IMAGE_BIN" ]] || fail "staged codex image binary is not readable: $STAGED_IMAGE_BIN"
+fi
 
 expected_sha="$(manifest_value api_sha256 || true)"
 expected_sha="${expected_sha:-$(manifest_value sha256 || true)}"
@@ -217,6 +227,14 @@ if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
     fail "staged usage worker binary sha256 mismatch: expected $expected_worker_sha, got $actual_worker_sha"
   fi
 fi
+expected_image_sha="$(manifest_value codex_image_sha256 || true)"
+actual_image_sha=""
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  actual_image_sha="$(sha256sum "$STAGED_IMAGE_BIN" | awk '{print $1}')"
+  if [[ -n "$expected_image_sha" && "$actual_image_sha" != "$expected_image_sha" ]]; then
+    fail "staged codex image binary sha256 mismatch: expected $expected_image_sha, got $actual_image_sha"
+  fi
+fi
 
 release_id="$(manifest_value release_id || true)"
 git_commit="$(manifest_value git_commit || true)"
@@ -232,6 +250,10 @@ if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
   log "staged_usage_worker_binary=$STAGED_WORKER_BIN"
   log "staged_usage_worker_sha256=$actual_worker_sha"
 fi
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  log "staged_codex_image_binary=$STAGED_IMAGE_BIN"
+  log "staged_codex_image_sha256=$actual_image_sha"
+fi
 
 systemctl is-active juicefs-llm-access.service >/dev/null || fail "juicefs-llm-access.service is not active"
 findmnt -T /mnt/llm-access >/dev/null || fail "/mnt/llm-access is not mounted"
@@ -239,6 +261,9 @@ sudo install -d -m 0755 "$BACKUP_DIR"
 if [[ -e "$STAGED_NEON_ENV" ]]; then
   [[ -r "$STAGED_NEON_ENV" ]] || fail "staged llm-access runtime env is not readable: $STAGED_NEON_ENV"
   require_env_file_var "$STAGED_NEON_ENV" LLM_ACCESS_CONTROL_DATABASE_URL "staged llm-access runtime env"
+  if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+    require_env_file_var "$STAGED_NEON_ENV" LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL "staged llm-access runtime env"
+  fi
   require_env_file_var "$STAGED_NEON_ENV" KIRO_THINKING_SIGNATURE_SECRET "staged llm-access runtime env"
   install -d -m 0755 "$(dirname "$NEON_ENV_PATH")"
   if sudo test -e "$NEON_ENV_PATH"; then
@@ -250,6 +275,9 @@ if [[ -e "$STAGED_NEON_ENV" ]]; then
 fi
 sudo test -r "$NEON_ENV_PATH" || fail "missing shared llm-access runtime env: $NEON_ENV_PATH"
 require_env_file_var_with_sudo "$NEON_ENV_PATH" LLM_ACCESS_CONTROL_DATABASE_URL "shared llm-access runtime env"
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  require_env_file_var_with_sudo "$NEON_ENV_PATH" LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL "shared llm-access runtime env"
+fi
 require_env_file_var_with_sudo "$NEON_ENV_PATH" KIRO_THINKING_SIGNATURE_SECRET "shared llm-access runtime env"
 if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
   if findmnt -T /mnt/llm-access-usage >/dev/null; then
@@ -272,18 +300,27 @@ if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]] && syste
 elif [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
   log "$WORKER_SERVICE is not active before activation; continuing with install"
 fi
+if [[ "$ACTIVATE_TARGET" == "image" ]] && systemctl is-active "$IMAGE_SERVICE" >/dev/null; then
+  log "$IMAGE_SERVICE is active before activation"
+  curl -fsS "$IMAGE_HEALTH_URL" >/dev/null || log "pre-activation codex image health check failed; continuing with restart"
+elif [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  log "$IMAGE_SERVICE is not active before activation; continuing with install"
+fi
 
 timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
 backup_path="$BACKUP_DIR/llm-access.$timestamp"
 worker_backup_path="$BACKUP_DIR/llm-access-usage-worker.$timestamp"
+image_backup_path="$BACKUP_DIR/llm-access-codex-image.$timestamp"
 neon_env_backup_path="$BACKUP_DIR/neon.env.$timestamp"
 service_unit_backup_path="$BACKUP_DIR/llm-access.service.$timestamp"
 worker_service_unit_backup_path="$BACKUP_DIR/llm-access-usage-worker.service.$timestamp"
+image_service_unit_backup_path="$BACKUP_DIR/llm-access-codex-image.service.$timestamp"
 usage_mount_service_unit_backup_path="$BACKUP_DIR/juicefs-llm-access-usage.service.$timestamp"
 
 reload_required=0
 installed_sha=""
 installed_worker_sha=""
+installed_image_sha=""
 
 if [[ -e "$STAGED_NEON_ENV" && -e "$BACKUP_DIR/neon.env.preinstall" ]]; then
   sudo mv "$BACKUP_DIR/neon.env.preinstall" "$neon_env_backup_path"
@@ -310,6 +347,14 @@ if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
     reload_required=1
   fi
 fi
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  install_binary "$STAGED_IMAGE_BIN" "$IMAGE_INSTALL_PATH" "$image_backup_path" "$actual_image_sha"
+  installed_image_sha="$(sudo sha256sum "$IMAGE_INSTALL_PATH" | awk '{print $1}')"
+  if [[ -n "$STAGED_IMAGE_SERVICE_UNIT" ]]; then
+    install_service_unit "$STAGED_IMAGE_SERVICE_UNIT" "$IMAGE_SERVICE_UNIT_INSTALL_PATH" "$image_service_unit_backup_path"
+    reload_required=1
+  fi
+fi
 
 if [[ "$reload_required" == "1" ]]; then
   log "reloading systemd units"
@@ -356,6 +401,9 @@ fi
 if [[ "$ACTIVATE_TARGET" == "api" || "$ACTIVATE_TARGET" == "both" ]]; then
   restart_and_verify "$SERVICE" "$HEALTH_URL" "$backup_path"
 fi
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  restart_and_verify "$IMAGE_SERVICE" "$IMAGE_HEALTH_URL" "$image_backup_path"
+fi
 
 log "activation succeeded"
 if [[ "$ACTIVATE_TARGET" == "api" || "$ACTIVATE_TARGET" == "both" ]]; then
@@ -370,6 +418,11 @@ if [[ "$ACTIVATE_TARGET" == "worker" || "$ACTIVATE_TARGET" == "both" ]]; then
   printf '\n'
   systemctl show "$WORKER_SERVICE" -p ActiveState -p SubState -p MainPID -p ExecMainStartTimestamp -p NRestarts --no-pager
 fi
+if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  curl -fsS "$IMAGE_HEALTH_URL"
+  printf '\n'
+  systemctl show "$IMAGE_SERVICE" -p ActiveState -p SubState -p MainPID -p ExecMainStartTimestamp -p NRestarts --no-pager
+fi
 
 rollback_cmd=""
 if [[ "$ACTIVATE_TARGET" == "both" ]]; then
@@ -400,6 +453,15 @@ elif [[ "$ACTIVATE_TARGET" == "api" ]]; then
     rollback_cmd+=" && sudo cp -a \"$service_unit_backup_path\" \"$SERVICE_UNIT_INSTALL_PATH\""
   fi
   rollback_cmd+=" && sudo systemctl daemon-reload && sudo systemctl restart \"$SERVICE\""
+elif [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  rollback_cmd="sudo cp -a \"$image_backup_path\" \"$IMAGE_INSTALL_PATH\""
+  if [[ -e "$neon_env_backup_path" ]]; then
+    rollback_cmd="sudo cat \"$neon_env_backup_path\" | tee \"$NEON_ENV_PATH\" >/dev/null && chmod 0600 \"$NEON_ENV_PATH\" && $rollback_cmd"
+  fi
+  if [[ -n "$STAGED_IMAGE_SERVICE_UNIT" ]]; then
+    rollback_cmd+=" && sudo cp -a \"$image_service_unit_backup_path\" \"$IMAGE_SERVICE_UNIT_INSTALL_PATH\""
+  fi
+  rollback_cmd+=" && sudo systemctl daemon-reload && sudo systemctl restart \"$IMAGE_SERVICE\""
 else
   rollback_cmd="sudo cp -a \"$worker_backup_path\" \"$WORKER_INSTALL_PATH\""
   if [[ -e "$neon_env_backup_path" ]]; then
@@ -428,6 +490,8 @@ Installed llm-access release:
   api_backup: ${installed_sha:+$backup_path}
   usage_worker_sha256: ${installed_worker_sha:-skipped}
   usage_worker_backup: ${installed_worker_sha:+$worker_backup_path}
+  codex_image_sha256: ${installed_image_sha:-skipped}
+  codex_image_backup: ${installed_image_sha:+$image_backup_path}
   neon_env: $NEON_ENV_PATH
 
 Rollback command if needed:
diff --git a/scripts/prepare_llm_access_cloud_release.sh b/scripts/prepare_llm_access_cloud_release.sh
index 08695b7f..8f4af54e 100755
--- a/scripts/prepare_llm_access_cloud_release.sh
+++ b/scripts/prepare_llm_access_cloud_release.sh
@@ -111,6 +111,7 @@ LOCAL_NEON_ENV_FILE="$(expand_path "$LOCAL_NEON_ENV_FILE")"
 [[ -r "$GCP_SSH_KEY" ]] || fail "SSH key is not readable: $GCP_SSH_KEY"
 [[ -r "$LOCAL_NEON_ENV_FILE" ]] || fail "local llm-access runtime env is not readable: $LOCAL_NEON_ENV_FILE"
 require_env_file_var "$LOCAL_NEON_ENV_FILE" LLM_ACCESS_CONTROL_DATABASE_URL "local llm-access runtime env"
+require_env_file_var "$LOCAL_NEON_ENV_FILE" LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL "local llm-access runtime env"
 require_env_file_var "$LOCAL_NEON_ENV_FILE" KIRO_THINKING_SIGNATURE_SECRET "local llm-access runtime env"
 
 cd "$ROOT_DIR"
@@ -126,18 +127,20 @@ df -h "$CARGO_TARGET_DIR" >/dev/null
 export CARGO_TARGET_DIR
 
 log "running llm-access test suite"
-cargo test -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access --jobs "$BUILD_JOBS"
+cargo test -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access -p llm-access-codex-image --jobs "$BUILD_JOBS"
 
 log "running llm-access clippy"
-cargo clippy -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access --jobs "$BUILD_JOBS" -- -D warnings
+cargo clippy -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access -p llm-access-codex-image --jobs "$BUILD_JOBS" -- -D warnings
 
 log "building release binaries"
-cargo build -p llm-access --release --jobs "$BUILD_JOBS"
+cargo build -p llm-access -p llm-access-codex-image --release --jobs "$BUILD_JOBS"
 
 API_BIN="$CARGO_TARGET_DIR/release/llm-access"
 WORKER_BIN="$CARGO_TARGET_DIR/release/llm-access-usage-worker"
+IMAGE_BIN="$CARGO_TARGET_DIR/release/llm-access-codex-image"
 [[ -x "$API_BIN" ]] || fail "built API binary not found or not executable: $API_BIN"
 [[ -x "$WORKER_BIN" ]] || fail "built usage worker binary not found or not executable: $WORKER_BIN"
+[[ -x "$IMAGE_BIN" ]] || fail "built codex image binary not found or not executable: $IMAGE_BIN"
 
 GIT_COMMIT="$(git rev-parse HEAD)"
 GIT_SHORT="$(git rev-parse --short=12 HEAD)"
@@ -145,29 +148,35 @@ RELEASE_ID="${RELEASE_ID:-$(date -u +%Y%m%dT%H%M%SZ)-$GIT_SHORT}"
 OUT_DIR="${LLM_ACCESS_RELEASE_OUT:-$ROOT_DIR/tmp/llm-access-cloud-release/$RELEASE_ID}"
 STAGED_BIN="$OUT_DIR/llm-access.$RELEASE_ID"
 STAGED_WORKER_BIN="$OUT_DIR/llm-access-usage-worker.$RELEASE_ID"
+STAGED_IMAGE_BIN="$OUT_DIR/llm-access-codex-image.$RELEASE_ID"
 STAGED_NEON_ENV="$OUT_DIR/llm-access-neon.env.$RELEASE_ID"
 MANIFEST="$OUT_DIR/release.$RELEASE_ID.env"
 SHA_FILE="$OUT_DIR/SHA256SUMS.$RELEASE_ID"
 RENDER_DIR="$OUT_DIR/rendered"
 STAGED_SERVICE_UNIT="$OUT_DIR/llm-access.service.release"
 STAGED_WORKER_SERVICE_UNIT="$OUT_DIR/llm-access-usage-worker.service.release"
+STAGED_IMAGE_SERVICE_UNIT="$OUT_DIR/llm-access-codex-image.service.release"
 STAGED_USAGE_MOUNT_SERVICE_UNIT="$OUT_DIR/juicefs-llm-access-usage.service.release"
 
 mkdir -p "$OUT_DIR"
 "$RENDER_SCRIPT" "$RENDER_DIR"
 cp "$API_BIN" "$STAGED_BIN"
 cp "$WORKER_BIN" "$STAGED_WORKER_BIN"
+cp "$IMAGE_BIN" "$STAGED_IMAGE_BIN"
 cp "$LOCAL_NEON_ENV_FILE" "$STAGED_NEON_ENV"
 cp "$RENDER_DIR/llm-access.service" "$STAGED_SERVICE_UNIT"
 cp "$RENDER_DIR/llm-access-usage-worker.service" "$STAGED_WORKER_SERVICE_UNIT"
+cp "$RENDER_DIR/llm-access-codex-image.service" "$STAGED_IMAGE_SERVICE_UNIT"
 cp "$RENDER_DIR/juicefs-llm-access-usage.service" "$STAGED_USAGE_MOUNT_SERVICE_UNIT"
-chmod 0755 "$STAGED_BIN" "$STAGED_WORKER_BIN"
+chmod 0755 "$STAGED_BIN" "$STAGED_WORKER_BIN" "$STAGED_IMAGE_BIN"
 chmod 0600 "$STAGED_NEON_ENV"
 API_BIN_SHA="$(sha256sum "$STAGED_BIN" | awk '{print $1}')"
 WORKER_BIN_SHA="$(sha256sum "$STAGED_WORKER_BIN" | awk '{print $1}')"
+IMAGE_BIN_SHA="$(sha256sum "$STAGED_IMAGE_BIN" | awk '{print $1}')"
 {
   printf '%s  %s\n' "$API_BIN_SHA" "llm-access.$RELEASE_ID"
   printf '%s  %s\n' "$WORKER_BIN_SHA" "llm-access-usage-worker.$RELEASE_ID"
+  printf '%s  %s\n' "$IMAGE_BIN_SHA" "llm-access-codex-image.$RELEASE_ID"
 } >"$SHA_FILE"
 
 cat >"$MANIFEST" <<EOF
@@ -181,6 +190,8 @@ api_sha256=$API_BIN_SHA
 api_binary=llm-access.$RELEASE_ID
 usage_worker_sha256=$WORKER_BIN_SHA
 usage_worker_binary=llm-access-usage-worker.$RELEASE_ID
+codex_image_sha256=$IMAGE_BIN_SHA
+codex_image_binary=llm-access-codex-image.$RELEASE_ID
 control_neon_env=llm-access-neon.env.$RELEASE_ID
 runtime_env=llm-access-neon.env.$RELEASE_ID
 EOF
@@ -202,11 +213,13 @@ log "uploading release $RELEASE_ID to $GCP_DEST:$REMOTE_RELEASE_DIR"
 scp "${SSH_OPTS[@]}" \
   "$STAGED_BIN" \
   "$STAGED_WORKER_BIN" \
+  "$STAGED_IMAGE_BIN" \
   "$STAGED_NEON_ENV" \
   "$MANIFEST" \
   "$SHA_FILE" \
   "$STAGED_SERVICE_UNIT" \
   "$STAGED_WORKER_SERVICE_UNIT" \
+  "$STAGED_IMAGE_SERVICE_UNIT" \
   "$STAGED_USAGE_MOUNT_SERVICE_UNIT" \
   "$REMOTE_SCRIPT" \
   "$GCP_DEST:$REMOTE_RELEASE_DIR/"
@@ -215,10 +228,11 @@ log "updating remote latest pointers"
 ssh "${SSH_OPTS[@]}" "$GCP_DEST" "
   set -e
   cd $REMOTE_RELEASE_DIR_Q
-  chmod 0755 $REMOTE_SCRIPT_NAME llm-access.$RELEASE_ID llm-access-usage-worker.$RELEASE_ID
+  chmod 0755 $REMOTE_SCRIPT_NAME llm-access.$RELEASE_ID llm-access-usage-worker.$RELEASE_ID llm-access-codex-image.$RELEASE_ID
   sha256sum -c SHA256SUMS.$RELEASE_ID
   ln -sfn llm-access.$RELEASE_ID llm-access.latest
   ln -sfn llm-access-usage-worker.$RELEASE_ID llm-access-usage-worker.latest
+  ln -sfn llm-access-codex-image.$RELEASE_ID llm-access-codex-image.latest
   ln -sfn llm-access-neon.env.$RELEASE_ID llm-access-neon.env.latest
   ln -sfn release.$RELEASE_ID.env release.latest.env
 "
@@ -230,6 +244,7 @@ Prepared llm-access cloud release:
   git_commit: $GIT_COMMIT
   api_sha256: $API_BIN_SHA
   usage_worker_sha256: $WORKER_BIN_SHA
+  codex_image_sha256: $IMAGE_BIN_SHA
   local_runtime_env: $LOCAL_NEON_ENV_FILE
   remote_dir: $REMOTE_RELEASE_DIR
 
diff --git a/scripts/release_llm_access_cloud_codex_image_only.sh b/scripts/release_llm_access_cloud_codex_image_only.sh
new file mode 100755
index 00000000..ef248007
--- /dev/null
+++ b/scripts/release_llm_access_cloud_codex_image_only.sh
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CONFIG_FILE=""
+REMOTE_SCRIPT_NAME="activate_llm_access_cloud_release.sh"
+RENDER_DIR="$(mktemp -d "$ROOT_DIR/tmp/llm-access-cloud-codex-image-only.XXXXXX")"
+
+cleanup() {
+  rm -rf "$RENDER_DIR"
+}
+trap cleanup EXIT
+
+fail() {
+  printf '[llm-access-release-image][ERROR] %s\n' "$*" >&2
+  exit 1
+}
+
+expand_path() {
+  case "$1" in
+    "~")
+      printf '%s\n' "$HOME"
+      ;;
+    "~/"*)
+      printf '%s/%s\n' "$HOME" "${1#"~/"}"
+      ;;
+    *)
+      printf '%s\n' "$1"
+      ;;
+  esac
+}
+
+default_config_file() {
+  local preferred="$ROOT_DIR/.local/llm-access-cloud-release-aws.env"
+  local legacy="$ROOT_DIR/.local/llm-access-cloud-release.env"
+  if [[ -n "${LLM_ACCESS_CLOUD_RELEASE_CONFIG:-}" ]]; then
+    printf '%s\n' "$LLM_ACCESS_CLOUD_RELEASE_CONFIG"
+  elif [[ -r "$preferred" ]]; then
+    printf '%s\n' "$preferred"
+  else
+    printf '%s\n' "$legacy"
+  fi
+}
+
+require_var() {
+  local name="$1"
+  [[ -n "${!name:-}" ]] || fail "missing required config value: $name in $CONFIG_FILE"
+}
+
+CONFIG_FILE="$(default_config_file)"
+[[ -r "$CONFIG_FILE" ]] || fail "missing config file: $CONFIG_FILE"
+# shellcheck source=/dev/null
+source "$CONFIG_FILE"
+
+require_var GCP_SSH_KEY
+require_var REMOTE_RELEASE_DIR
+if [[ -z "${GCP_DEST:-}" ]]; then
+  require_var GCP_USER
+  require_var GCP_HOST
+  GCP_DEST="$GCP_USER@$GCP_HOST"
+fi
+
+GCP_SSH_KEY="$(expand_path "$GCP_SSH_KEY")"
+SSH_OPTS=(-i "$GCP_SSH_KEY" -o IdentitiesOnly=yes -o BatchMode=yes)
+
+"$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
+"$ROOT_DIR/scripts/render_llm_access_cloud_bundle.sh" "$RENDER_DIR"
+
+scp "${SSH_OPTS[@]}" \
+  "$RENDER_DIR/llm-access-codex-image.service" \
+  "$GCP_DEST:$REMOTE_RELEASE_DIR/llm-access-codex-image.service.release"
+
+ssh "${SSH_OPTS[@]}" "$GCP_DEST" \
+  "LLM_ACCESS_ACTIVATE_TARGET=image LLM_ACCESS_STAGED_IMAGE_SERVICE_UNIT=$REMOTE_RELEASE_DIR/llm-access-codex-image.service.release $REMOTE_RELEASE_DIR/$REMOTE_SCRIPT_NAME"
diff --git a/scripts/render_llm_access_cloud_bundle.sh b/scripts/render_llm_access_cloud_bundle.sh
index afa52ce1..1d9d83c1 100755
--- a/scripts/render_llm_access_cloud_bundle.sh
+++ b/scripts/render_llm_access_cloud_bundle.sh
@@ -7,6 +7,7 @@ OUT_DIR="${1:?usage: scripts/render_llm_access_cloud_bundle.sh <out-dir>}"
 mkdir -p "$OUT_DIR"
 cp "$ROOT_DIR/deployment-examples/systemd/llm-access.service.template" "$OUT_DIR/llm-access.service"
 cp "$ROOT_DIR/deployment-examples/systemd/llm-access-usage-worker.service.template" "$OUT_DIR/llm-access-usage-worker.service"
+cp "$ROOT_DIR/deployment-examples/systemd/llm-access-codex-image.service.template" "$OUT_DIR/llm-access-codex-image.service"
 cp "$ROOT_DIR/deployment-examples/systemd/llm-access-juicefs.mount.template" "$OUT_DIR/mnt-llm\\x2daccess.mount"
 cp "$ROOT_DIR/deployment-examples/systemd/juicefs-llm-access-usage.service.template" "$OUT_DIR/juicefs-llm-access-usage.service"
 cp "$ROOT_DIR/deployment-examples/systemd/juicefs-llm-access.resource-guard.conf" "$OUT_DIR/juicefs-llm-access.resource-guard.conf"
diff --git a/scripts/test_llm_access_cloud_bundle.sh b/scripts/test_llm_access_cloud_bundle.sh
index 86f98ec0..d4fd971f 100755
--- a/scripts/test_llm_access_cloud_bundle.sh
+++ b/scripts/test_llm_access_cloud_bundle.sh
@@ -18,6 +18,7 @@ assert_absent() {
 
 test -s "$OUT_DIR/llm-access.service"
 test -s "$OUT_DIR/llm-access-usage-worker.service"
+test -s "$OUT_DIR/llm-access-codex-image.service"
 test -s "$OUT_DIR/mnt-llm\\x2daccess.mount"
 test -s "$OUT_DIR/juicefs-llm-access-usage.service"
 test -s "$OUT_DIR/juicefs-llm-access.resource-guard.conf"
@@ -95,6 +96,11 @@ grep -F 'Environment=STATICFLOW_LOG_DIR=/var/log/staticflow-runtime' "$OUT_DIR/l
 grep -F 'Environment=STATICFLOW_LOG_SERVICE=llm-access' "$OUT_DIR/llm-access.service"
 grep -F 'Environment=mimalloc_generic_collect=1000' "$OUT_DIR/llm-access.service"
 grep -F 'Environment=mimalloc_generic_collect=1000' "$OUT_DIR/llm-access-usage-worker.service"
+grep -F "ExecStart=/usr/bin/bash -lc 'set -a; . /mnt/llm-access/config/neon.env; exec /usr/local/bin/llm-access-codex-image serve --bind 127.0.0.1:19082 --state-root /mnt/llm-access --postgres-control-database-url-env LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL --request-cache-url-env LLM_ACCESS_REQUEST_CACHE_URL --request-cache-key-prefix llma --image-log-dir /var/lib/staticflow/llm-access/codex-image-logs'" "$OUT_DIR/llm-access-codex-image.service"
+grep -F '@codex_image path /v1/images/generations /v1/images/edits /api/codex-gateway/images/generations /api/codex-gateway/images/edits /api/codex-gateway/v1/images/generations /api/codex-gateway/v1/images/edits /api/llm-gateway/v1/images/generations /api/llm-gateway/v1/images/edits' "$OUT_DIR/Caddyfile"
+codex_image_line="$(grep -n 'handle @codex_image' "$OUT_DIR/Caddyfile" | head -n1 | cut -d: -f1)"
+llm_access_line="$(grep -n 'handle @llm_access' "$OUT_DIR/Caddyfile" | head -n1 | cut -d: -f1)"
+test "$codex_image_line" -lt "$llm_access_line"
 grep -F 'mountpoint -q "$mount_point"' "$OUT_DIR/staticflow-wait-llm-access-state"
 grep -F 'control_database_url="${LLM_ACCESS_CONTROL_DATABASE_URL:-}"' "$OUT_DIR/staticflow-wait-llm-access-state"
 grep -F 'mode="mount-only"' "$OUT_DIR/staticflow-wait-llm-access-state"
diff --git a/scripts/test_llm_access_cloud_release_scripts.sh b/scripts/test_llm_access_cloud_release_scripts.sh
index fd96009e..bdced202 100755
--- a/scripts/test_llm_access_cloud_release_scripts.sh
+++ b/scripts/test_llm_access_cloud_release_scripts.sh
@@ -6,9 +6,10 @@ LOCAL_SCRIPT="$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
 REMOTE_SCRIPT="$ROOT_DIR/scripts/activate_llm_access_cloud_release.sh"
 API_ONLY_SCRIPT="$ROOT_DIR/scripts/release_llm_access_cloud_api_only.sh"
 WORKER_ONLY_SCRIPT="$ROOT_DIR/scripts/release_llm_access_cloud_worker_only.sh"
+IMAGE_ONLY_SCRIPT="$ROOT_DIR/scripts/release_llm_access_cloud_codex_image_only.sh"
 CONFIG_EXAMPLE="$ROOT_DIR/conf/llm-access-cloud-release.env.example"
 
-for script in "$LOCAL_SCRIPT" "$REMOTE_SCRIPT" "$API_ONLY_SCRIPT" "$WORKER_ONLY_SCRIPT"; do
+for script in "$LOCAL_SCRIPT" "$REMOTE_SCRIPT" "$API_ONLY_SCRIPT" "$WORKER_ONLY_SCRIPT" "$IMAGE_ONLY_SCRIPT"; do
   test -x "$script"
   bash -n "$script"
 done
@@ -16,13 +17,13 @@ done
 test -s "$CONFIG_EXAMPLE"
 
 if command -v shellcheck >/dev/null 2>&1; then
-  shellcheck "$LOCAL_SCRIPT" "$REMOTE_SCRIPT" "$API_ONLY_SCRIPT" "$WORKER_ONLY_SCRIPT"
+  shellcheck "$LOCAL_SCRIPT" "$REMOTE_SCRIPT" "$API_ONLY_SCRIPT" "$WORKER_ONLY_SCRIPT" "$IMAGE_ONLY_SCRIPT"
 fi
 
 grep -F 'CARGO_TARGET_DIR' "$LOCAL_SCRIPT" >/dev/null
-grep -F 'cargo test -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access' "$LOCAL_SCRIPT" >/dev/null
-grep -F 'cargo clippy -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access' "$LOCAL_SCRIPT" >/dev/null
-grep -F 'cargo build -p llm-access --release' "$LOCAL_SCRIPT" >/dev/null
+grep -F 'cargo test -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access -p llm-access-codex-image' "$LOCAL_SCRIPT" >/dev/null
+grep -F 'cargo clippy -p llm-usage-journal -p llm-access-core -p llm-access-store -p llm-access -p llm-access-codex-image' "$LOCAL_SCRIPT" >/dev/null
+grep -F 'cargo build -p llm-access -p llm-access-codex-image --release' "$LOCAL_SCRIPT" >/dev/null
 grep -F 'render_llm_access_cloud_bundle.sh' "$LOCAL_SCRIPT" >/dev/null
 grep -F 'scp ' "$LOCAL_SCRIPT" >/dev/null
 grep -F 'llm-access.latest' "$LOCAL_SCRIPT" >/dev/null
@@ -32,6 +33,8 @@ grep -F '.local/llm-access-cloud-release-aws.env' "$API_ONLY_SCRIPT" >/dev/null
 grep -F '.local/llm-access-cloud-release.env' "$API_ONLY_SCRIPT" >/dev/null
 grep -F '.local/llm-access-cloud-release-aws.env' "$WORKER_ONLY_SCRIPT" >/dev/null
 grep -F '.local/llm-access-cloud-release.env' "$WORKER_ONLY_SCRIPT" >/dev/null
+grep -F '.local/llm-access-cloud-release-aws.env' "$IMAGE_ONLY_SCRIPT" >/dev/null
+grep -F '.local/llm-access-cloud-release.env' "$IMAGE_ONLY_SCRIPT" >/dev/null
 grep -F 'source "$CONFIG_FILE"' "$LOCAL_SCRIPT" >/dev/null
 grep -F 'KIRO_THINKING_SIGNATURE_SECRET' "$LOCAL_SCRIPT" >/dev/null
 ! grep -F 'pgrep' "$LOCAL_SCRIPT" >/dev/null
@@ -44,12 +47,18 @@ grep -F 'sudo mv -f' "$REMOTE_SCRIPT" >/dev/null
 grep -F 'systemctl restart' "$REMOTE_SCRIPT" >/dev/null
 grep -F 'http://127.0.0.1:19080/healthz' "$REMOTE_SCRIPT" >/dev/null
 grep -F 'KIRO_THINKING_SIGNATURE_SECRET' "$REMOTE_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL' "$LOCAL_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL' "$REMOTE_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_ACTIVATE_TARGET=api' "$API_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_STAGED_SERVICE_UNIT=' "$API_ONLY_SCRIPT" >/dev/null
 grep -F 'render_llm_access_cloud_bundle.sh' "$API_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_ACTIVATE_TARGET=worker' "$WORKER_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_STAGED_WORKER_SERVICE_UNIT=' "$WORKER_ONLY_SCRIPT" >/dev/null
 grep -F 'render_llm_access_cloud_bundle.sh' "$WORKER_ONLY_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_ACTIVATE_TARGET=image' "$IMAGE_ONLY_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_STAGED_IMAGE_SERVICE_UNIT=' "$IMAGE_ONLY_SCRIPT" >/dev/null
+grep -F 'render_llm_access_cloud_bundle.sh' "$IMAGE_ONLY_SCRIPT" >/dev/null
+grep -F 'llm-access-codex-image.latest' "$REMOTE_SCRIPT" >/dev/null
 
 grep -F 'GCP_HOST=' "$CONFIG_EXAMPLE" >/dev/null
 grep -F 'GCP_SSH_KEY=' "$CONFIG_EXAMPLE" >/dev/null

From be0a705f45f136df2b3fd42b81b442c51ef495fe Mon Sep 17 00:00:00 2001
From: LB7666 <acking-you@foxmail.com>
Date: Fri, 26 Jun 2026 12:39:29 +0800
Subject: [PATCH 2/3] fix(llm-access): address codex image gateway review

---
 Cargo.lock                                    |   2 +-
 .../frontend/src/pages/admin_llm_gateway.rs   |   2 +-
 crates/llm-access-codex-image/Cargo.toml      |   2 +-
 crates/llm-access-codex-image/src/limiter.rs  | 103 ++++-
 crates/llm-access-codex-image/src/logging.rs  | 184 +++++++-
 crates/llm-access-codex-image/src/main.rs     | 407 ++++++++++++++----
 .../tests/codex_image_dispatch.rs             |  33 +-
 .../tests/codex_image_request.rs              |  33 +-
 crates/llm-access-codex/src/request/mod.rs    |   6 +-
 .../src/request/normalization.rs              |  69 +++
 .../migrations/postgres/0001_init.sql         |   1 -
 crates/llm-access-migrations/src/lib.rs       |  13 +
 crates/llm-access-store/src/postgres.rs       |  26 ++
 crates/llm-access/src/provider.rs             |   1 -
 crates/llm-access/src/provider/codex_auth.rs  |  29 +-
 .../llm-access-codex-image.service.template   |   4 +
 scripts/activate_llm_access_cloud_release.sh  |   8 +-
 scripts/prepare_llm_access_cloud_release.sh   |  11 +-
 scripts/release_llm_access_cloud_api_only.sh  |   2 +-
 ...lease_llm_access_cloud_codex_image_only.sh |   4 +-
 .../release_llm_access_cloud_worker_only.sh   |   2 +-
 .../test_llm_access_cloud_release_scripts.sh  |   4 +
 22 files changed, 785 insertions(+), 161 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index d1efb78e..7c5c30c0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5760,8 +5760,8 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2 0.10.9",
+ "tempfile",
  "tokio",
- "tower 0.5.2",
  "tracing",
  "tracing-subscriber",
 ]
diff --git a/crates/frontend/src/pages/admin_llm_gateway.rs b/crates/frontend/src/pages/admin_llm_gateway.rs
index e91c33a7..9ebf3ff1 100644
--- a/crates/frontend/src/pages/admin_llm_gateway.rs
+++ b/crates/frontend/src/pages/admin_llm_gateway.rs
@@ -504,7 +504,7 @@ fn account_image_rate_limit_bucket<'a>(
         let display_name = bucket.display_name.to_ascii_lowercase();
         [limit_id.as_str(), limit_name.as_str(), display_name.as_str()]
             .iter()
-            .any(|value| value.contains("gpt-image") || value.contains("image"))
+            .any(|value| value.contains("image"))
     })
 }
 
diff --git a/crates/llm-access-codex-image/Cargo.toml b/crates/llm-access-codex-image/Cargo.toml
index bd77ced7..f58bf581 100644
--- a/crates/llm-access-codex-image/Cargo.toml
+++ b/crates/llm-access-codex-image/Cargo.toml
@@ -24,4 +24,4 @@ tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 
 [dev-dependencies]
-tower = { version = "0.5", features = ["util"] }
+tempfile = "3"
diff --git a/crates/llm-access-codex-image/src/limiter.rs b/crates/llm-access-codex-image/src/limiter.rs
index 9abd821a..412e0c3f 100644
--- a/crates/llm-access-codex-image/src/limiter.rs
+++ b/crates/llm-access-codex-image/src/limiter.rs
@@ -1,6 +1,7 @@
 use std::{
     collections::HashMap,
-    sync::{Arc, Mutex},
+    sync::{Arc, Mutex, MutexGuard},
+    time::{Duration, Instant},
 };
 
 use llm_access_core::store::DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY;
@@ -11,6 +12,18 @@ pub struct ImageAccountLimiter {
     states: Arc<Mutex<HashMap<String, u64>>>,
 }
 
+/// Process-local limiter for key-level Codex image throttling.
+#[derive(Clone, Debug, Default)]
+pub struct ImageKeyLimiter {
+    states: Arc<Mutex<HashMap<String, ImageKeyLimitState>>>,
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct ImageKeyLimitState {
+    in_flight: u64,
+    last_start: Option<Instant>,
+}
+
 /// Permit held for the lifetime of one upstream image request.
 #[derive(Debug)]
 pub struct ImageAccountPermit {
@@ -18,11 +31,36 @@ pub struct ImageAccountPermit {
     states: Arc<Mutex<HashMap<String, u64>>>,
 }
 
+/// Permit held for one key-level image request.
+#[derive(Debug)]
+pub struct ImageKeyPermit {
+    scope: String,
+    states: Arc<Mutex<HashMap<String, ImageKeyLimitState>>>,
+}
+
+/// Rejection metadata for a key-level image request limit.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageKeyLimitRejection {
+    /// Stable reason for logging and downstream response text.
+    pub reason: &'static str,
+    /// Current in-flight requests for the scope.
+    pub in_flight: u64,
+    /// Configured max concurrency, when bounded.
+    pub max_concurrency: Option<u64>,
+    /// Configured min start interval, when bounded.
+    pub min_start_interval_ms: Option<u64>,
+}
+
 /// Returns the independent limiter scope used for image account concurrency.
 pub fn image_account_limiter_scope(account_name: &str) -> String {
     format!("account:codex-image:{account_name}")
 }
 
+/// Returns the independent limiter scope used for image key throttling.
+pub fn image_key_limiter_scope(key_id: &str) -> String {
+    format!("key:codex-image:{key_id}")
+}
+
 impl ImageAccountLimiter {
     /// Attempts to acquire one account image permit without waiting.
     pub fn try_acquire(
@@ -34,7 +72,7 @@ impl ImageAccountLimiter {
             .unwrap_or(DEFAULT_CODEX_IMAGE_GENERATION_MAX_CONCURRENCY)
             .max(1);
         let scope = image_account_limiter_scope(account_name);
-        let mut states = self.states.lock().expect("image limiter mutex poisoned");
+        let mut states = lock_unpoisoned(&self.states);
         let in_flight = states.entry(scope.clone()).or_default();
         if *in_flight >= limit {
             return None;
@@ -47,9 +85,52 @@ impl ImageAccountLimiter {
     }
 }
 
+impl ImageKeyLimiter {
+    /// Attempts to acquire one key image permit without waiting.
+    pub fn try_acquire(
+        &self,
+        key_id: &str,
+        max_concurrency: Option<u64>,
+        min_start_interval_ms: Option<u64>,
+    ) -> Result<ImageKeyPermit, ImageKeyLimitRejection> {
+        let max_concurrency = max_concurrency.filter(|value| *value > 0);
+        let min_interval = min_start_interval_ms
+            .filter(|value| *value > 0)
+            .map(Duration::from_millis);
+        let scope = image_key_limiter_scope(key_id);
+        let mut states = lock_unpoisoned(&self.states);
+        let state = states.entry(scope.clone()).or_default();
+        let concurrency_ready = max_concurrency
+            .map(|limit| state.in_flight < limit)
+            .unwrap_or(true);
+        let interval_ready = min_interval
+            .zip(state.last_start)
+            .map(|(interval, last_start)| last_start.elapsed() >= interval)
+            .unwrap_or(true);
+        if concurrency_ready && interval_ready {
+            state.in_flight = state.in_flight.saturating_add(1);
+            state.last_start = Some(Instant::now());
+            return Ok(ImageKeyPermit {
+                scope,
+                states: Arc::clone(&self.states),
+            });
+        }
+        Err(ImageKeyLimitRejection {
+            reason: if !concurrency_ready {
+                "key_max_concurrency"
+            } else {
+                "key_min_start_interval"
+            },
+            in_flight: state.in_flight,
+            max_concurrency,
+            min_start_interval_ms,
+        })
+    }
+}
+
 impl Drop for ImageAccountPermit {
     fn drop(&mut self) {
-        let mut states = self.states.lock().expect("image limiter mutex poisoned");
+        let mut states = lock_unpoisoned(&self.states);
         let Some(in_flight) = states.get_mut(&self.scope) else {
             return;
         };
@@ -59,3 +140,19 @@ impl Drop for ImageAccountPermit {
         }
     }
 }
+
+impl Drop for ImageKeyPermit {
+    fn drop(&mut self) {
+        let mut states = lock_unpoisoned(&self.states);
+        let Some(state) = states.get_mut(&self.scope) else {
+            return;
+        };
+        state.in_flight = state.in_flight.saturating_sub(1);
+    }
+}
+
+fn lock_unpoisoned<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
+    mutex
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
diff --git a/crates/llm-access-codex-image/src/logging.rs b/crates/llm-access-codex-image/src/logging.rs
index 725b6dbf..ba906c5a 100644
--- a/crates/llm-access-codex-image/src/logging.rs
+++ b/crates/llm-access-codex-image/src/logging.rs
@@ -1,5 +1,5 @@
 use std::{
-    fs::{self, OpenOptions},
+    fs::{self, File, OpenOptions},
     io::{BufWriter, Write},
     path::PathBuf,
     time::{SystemTime, UNIX_EPOCH},
@@ -72,7 +72,7 @@ pub struct ImageLogEvent {
     pub account_name: Option<String>,
     /// Normalized endpoint name.
     pub endpoint: String,
-    /// SHA-256 hash of the prompt.
+    /// SHA-256 correlation hash of the prompt; not a secrecy boundary.
     pub prompt_hash: String,
     /// Requested image size.
     pub size: Option<String>,
@@ -120,6 +120,9 @@ pub struct ImageLogConfig {
 pub struct ImageLogWriter {
     config: ImageLogConfig,
     active_started_at_ms: u64,
+    active_writer: Option<BufWriter<File>>,
+    active_bytes: u64,
+    sealed_sequence: u64,
 }
 
 impl ImageLogWriter {
@@ -128,46 +131,54 @@ impl ImageLogWriter {
         fs::create_dir_all(&config.log_dir).with_context(|| {
             format!("create codex image log directory `{}`", config.log_dir.display())
         })?;
+        let active_bytes = config
+            .log_dir
+            .join("codex-image-active.jsonl")
+            .metadata()
+            .map(|metadata| metadata.len())
+            .unwrap_or(0);
         Ok(Self {
             config,
             active_started_at_ms: now_ms(),
+            active_writer: None,
+            active_bytes,
+            sealed_sequence: 0,
         })
     }
 
     /// Appends one redacted event as a JSON line.
     pub fn append(&mut self, event: &ImageLogEvent) -> anyhow::Result<()> {
         self.rotate_if_needed()?;
-        let active_path = self.active_path();
-        let file = OpenOptions::new()
-            .create(true)
-            .append(true)
-            .open(&active_path)
-            .with_context(|| format!("open codex image log `{}`", active_path.display()))?;
-        let mut writer = BufWriter::new(file);
-        serde_json::to_writer(&mut writer, event).context("serialize codex image log event")?;
+        let line = serde_json::to_vec(event).context("serialize codex image log event")?;
+        let writer = self.active_writer()?;
+        writer
+            .write_all(&line)
+            .context("write codex image log event")?;
         writer
             .write_all(b"\n")
             .context("write codex image log newline")?;
         writer.flush().context("flush codex image log event")?;
+        self.active_bytes = self
+            .active_bytes
+            .saturating_add(u64::try_from(line.len() + 1).unwrap_or(u64::MAX));
         Ok(())
     }
 
     fn rotate_if_needed(&mut self) -> anyhow::Result<()> {
         let active_path = self.active_path();
-        let size_exceeded = active_path
-            .metadata()
-            .map(|metadata| metadata.len() >= self.config.max_file_bytes.max(1))
-            .unwrap_or(false);
+        let size_exceeded = self.active_bytes >= self.config.max_file_bytes.max(1);
         let age_exceeded = now_ms().saturating_sub(self.active_started_at_ms)
             >= self.config.max_file_age_ms.max(1);
         if !size_exceeded && !age_exceeded {
             return Ok(());
         }
+        if let Some(mut writer) = self.active_writer.take() {
+            writer
+                .flush()
+                .context("flush codex image log before rotation")?;
+        }
         if active_path.exists() {
-            let sealed_path = self
-                .config
-                .log_dir
-                .join(format!("codex-image-{}.jsonl", now_ms()));
+            let sealed_path = self.next_sealed_path();
             fs::rename(&active_path, &sealed_path).with_context(|| {
                 format!(
                     "rotate codex image log `{}` to `{}`",
@@ -177,9 +188,40 @@ impl ImageLogWriter {
             })?;
         }
         self.active_started_at_ms = now_ms();
+        self.active_bytes = 0;
         self.prune_sealed_logs()
     }
 
+    fn active_writer(&mut self) -> anyhow::Result<&mut BufWriter<File>> {
+        if self.active_writer.is_none() {
+            let active_path = self.active_path();
+            let file = OpenOptions::new()
+                .create(true)
+                .append(true)
+                .open(&active_path)
+                .with_context(|| format!("open codex image log `{}`", active_path.display()))?;
+            self.active_writer = Some(BufWriter::new(file));
+        }
+        Ok(self
+            .active_writer
+            .as_mut()
+            .expect("active writer just opened"))
+    }
+
+    fn next_sealed_path(&mut self) -> PathBuf {
+        loop {
+            self.sealed_sequence = self.sealed_sequence.saturating_add(1);
+            let path = self.config.log_dir.join(format!(
+                "codex-image-{}-{}.jsonl",
+                now_ms(),
+                self.sealed_sequence
+            ));
+            if !path.exists() {
+                return path;
+            }
+        }
+    }
+
     fn prune_sealed_logs(&self) -> anyhow::Result<()> {
         let mut files = fs::read_dir(&self.config.log_dir)
             .with_context(|| {
@@ -217,6 +259,11 @@ impl ImageLogWriter {
     fn active_path(&self) -> PathBuf {
         self.config.log_dir.join("codex-image-active.jsonl")
     }
+
+    #[cfg(test)]
+    fn force_active_started_at_ms(&mut self, active_started_at_ms: u64) {
+        self.active_started_at_ms = active_started_at_ms;
+    }
 }
 
 /// Builds a redacted log event that never stores raw prompts or base64 images.
@@ -260,3 +307,104 @@ fn now_ms() -> u64 {
         .map(|duration| duration.as_millis() as u64)
         .unwrap_or(0)
 }
+
+#[cfg(test)]
+mod tests {
+    use std::{fs, thread, time::Duration};
+
+    use super::*;
+
+    fn test_event(request_id: &str) -> ImageLogEvent {
+        build_image_log_event(ImageLogInput {
+            request_id,
+            key_id: "key-1",
+            key_name: "Key One",
+            account_name: Some("codex-a"),
+            endpoint: "generations",
+            prompt: "draw a lake",
+            size: Some("1024x1024"),
+            quality: Some("high"),
+            n: 1,
+            input_images: &[],
+            upstream: UpstreamLogInput {
+                status: Some(200),
+                duration_ms: 10,
+                failover_count: 0,
+                error_class: None,
+                response_image_count: Some(1),
+                response_image_bytes: Some(128),
+                usage_tokens: Some(12),
+                usage_missing: false,
+            },
+        })
+    }
+
+    fn sealed_logs(dir: &std::path::Path) -> Vec<PathBuf> {
+        let mut files = fs::read_dir(dir)
+            .expect("read log dir")
+            .filter_map(Result::ok)
+            .map(|entry| entry.path())
+            .filter(|path| {
+                path.file_name()
+                    .and_then(|name| name.to_str())
+                    .is_some_and(|name| {
+                        name.starts_with("codex-image-")
+                            && name.ends_with(".jsonl")
+                            && name != "codex-image-active.jsonl"
+                    })
+            })
+            .collect::<Vec<_>>();
+        files.sort();
+        files
+    }
+
+    #[test]
+    fn image_log_writer_rotates_by_size_and_prunes_sealed_logs() {
+        let temp = tempfile::TempDir::new().expect("temp dir");
+        let mut writer = ImageLogWriter::new(ImageLogConfig {
+            log_dir: temp.path().to_path_buf(),
+            max_file_bytes: 1,
+            max_file_age_ms: u64::MAX,
+            max_files: 2,
+        })
+        .expect("writer");
+
+        writer.append(&test_event("req-1")).expect("append 1");
+        thread::sleep(Duration::from_millis(2));
+        writer.append(&test_event("req-2")).expect("append 2");
+        thread::sleep(Duration::from_millis(2));
+        writer.append(&test_event("req-3")).expect("append 3");
+        thread::sleep(Duration::from_millis(2));
+        writer.append(&test_event("req-4")).expect("append 4");
+
+        let sealed = sealed_logs(temp.path());
+        assert_eq!(sealed.len(), 2);
+        assert!(temp.path().join("codex-image-active.jsonl").exists());
+        let sealed_names = sealed
+            .iter()
+            .filter_map(|path| path.file_name()?.to_str())
+            .collect::<Vec<_>>();
+        assert!(sealed_names
+            .iter()
+            .all(|name| *name != "codex-image-active.jsonl"));
+    }
+
+    #[test]
+    fn image_log_writer_rotates_by_age() {
+        let temp = tempfile::TempDir::new().expect("temp dir");
+        let mut writer = ImageLogWriter::new(ImageLogConfig {
+            log_dir: temp.path().to_path_buf(),
+            max_file_bytes: u64::MAX,
+            max_file_age_ms: 1,
+            max_files: 4,
+        })
+        .expect("writer");
+
+        writer.append(&test_event("req-1")).expect("append 1");
+        writer.force_active_started_at_ms(0);
+        writer.append(&test_event("req-2")).expect("append 2");
+
+        assert_eq!(sealed_logs(temp.path()).len(), 1);
+        assert!(temp.path().join("codex-image-active.jsonl").exists());
+    }
+}
diff --git a/crates/llm-access-codex-image/src/main.rs b/crates/llm-access-codex-image/src/main.rs
index 89a74bff..4e4deb13 100644
--- a/crates/llm-access-codex-image/src/main.rs
+++ b/crates/llm-access-codex-image/src/main.rs
@@ -1,6 +1,7 @@
 //! Standalone Codex image gateway executable.
 
 use std::{
+    collections::HashMap,
     net::SocketAddr,
     path::PathBuf,
     sync::{Arc, Mutex},
@@ -16,10 +17,11 @@ use axum::{
     routing::get,
     Router,
 };
+use bytes::BytesMut;
 use clap::{Parser, Subcommand};
 use llm_access_codex_image::{
     dispatch::{eligible_image_routes, should_failover_status},
-    limiter::ImageAccountLimiter,
+    limiter::{ImageAccountLimiter, ImageKeyLimitRejection, ImageKeyLimiter},
     logging::{
         build_image_log_event, ImageLogConfig, ImageLogInput, ImageLogWriter, UpstreamLogInput,
     },
@@ -28,7 +30,7 @@ use llm_access_codex_image::{
 use llm_access_core::{
     provider::{ProtocolFamily, ProviderType},
     store::{
-        codex_auth_access_token_expires_at_ms, AdminConfigStore, AuthenticatedKey, ControlStore,
+        codex_access_token_expires_at_ms, AdminConfigStore, AuthenticatedKey, ControlStore,
         ProviderCodexRoute, ProviderProxyConfig, ProviderRouteStore, DEFAULT_CODEX_CLIENT_VERSION,
         KEY_STATUS_ACTIVE,
     },
@@ -41,8 +43,8 @@ const DEFAULT_BIND_ADDR: &str = "127.0.0.1:19082";
 const DEFAULT_CONTROL_DATABASE_URL_ENV: &str = "LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL";
 const DEFAULT_REQUEST_CACHE_URL_ENV: &str = "LLM_ACCESS_REQUEST_CACHE_URL";
 const DEFAULT_REQUEST_CACHE_KEY_PREFIX: &str = "llma";
-const DEFAULT_UPSTREAM_BASE_URL: &str = "https://chatgpt.com/backend-api/codex";
 const MAX_IMAGE_REQUEST_BODY_BYTES: usize = 24 * 1024 * 1024;
+const MAX_IMAGE_UPSTREAM_RESPONSE_BODY_BYTES: u64 = 96 * 1024 * 1024;
 
 #[derive(Debug, Parser)]
 #[command(name = "llm-access-codex-image")]
@@ -76,7 +78,10 @@ struct ServeArgs {
 struct AppState {
     control: Arc<PostgresControlRepository>,
     limiter: Arc<ImageAccountLimiter>,
+    key_limiter: Arc<ImageKeyLimiter>,
     image_log: Arc<Mutex<ImageLogWriter>>,
+    default_client: reqwest::Client,
+    proxy_clients: Arc<Mutex<HashMap<String, reqwest::Client>>>,
     upstream_base: String,
     codex_client_version: String,
 }
@@ -104,6 +109,10 @@ async fn serve(args: ServeArgs) -> anyhow::Result<()> {
             .await
             .context("connect read-only postgres control repository")?,
     );
+    control
+        .verify_codex_image_gateway_schema()
+        .await
+        .context("verify codex image gateway control-plane schema")?;
     let runtime_config = control
         .get_admin_runtime_config()
         .await
@@ -121,10 +130,15 @@ async fn serve(args: ServeArgs) -> anyhow::Result<()> {
     let state = Arc::new(AppState {
         control,
         limiter: Arc::new(ImageAccountLimiter::default()),
+        key_limiter: Arc::new(ImageKeyLimiter::default()),
         image_log: Arc::new(Mutex::new(image_log)),
-        upstream_base: codex_upstream_base_url(),
-        codex_client_version: normalize_codex_client_version(&runtime_config.codex_client_version)
-            .unwrap_or_else(|| DEFAULT_CODEX_CLIENT_VERSION.to_string()),
+        default_client: provider_client(None)?,
+        proxy_clients: Arc::new(Mutex::new(HashMap::new())),
+        upstream_base: llm_access_codex::request::codex_upstream_base_url_from_env(),
+        codex_client_version: llm_access_codex::request::normalize_codex_client_version(
+            &runtime_config.codex_client_version,
+        )
+        .unwrap_or_else(|| DEFAULT_CODEX_CLIENT_VERSION.to_string()),
     });
     let app = Router::new()
         .route("/healthz", get(|| async { "ok" }))
@@ -244,6 +258,27 @@ fn reject_key(key: &AuthenticatedKey) -> Option<axum::response::Response> {
     None
 }
 
+fn image_key_limit_response(rejection: &ImageKeyLimitRejection) -> axum::response::Response {
+    (
+        StatusCode::TOO_MANY_REQUESTS,
+        format!(
+            "key image request limit reached: {} in_flight={} request_max_concurrency={} \
+             request_min_start_interval_ms={}",
+            rejection.reason,
+            rejection.in_flight,
+            rejection
+                .max_concurrency
+                .map(|value| value.to_string())
+                .unwrap_or_else(|| "unlimited".to_string()),
+            rejection
+                .min_start_interval_ms
+                .map(|value| value.to_string())
+                .unwrap_or_else(|| "unlimited".to_string()),
+        ),
+    )
+        .into_response()
+}
+
 async fn dispatch_image_request(
     state: &AppState,
     ctx: ImageDispatchRequest<'_>,
@@ -259,6 +294,40 @@ async fn dispatch_image_request(
         Ok(candidates) => candidates,
         Err(err) => return (err.status, err.message).into_response(),
     };
+    let key_limits = candidates
+        .first()
+        .map(|candidate| {
+            (candidate.request_max_concurrency, candidate.request_min_start_interval_ms)
+        })
+        .unwrap_or((None, None));
+    let _key_permit =
+        match state
+            .key_limiter
+            .try_acquire(&ctx.key.key_id, key_limits.0, key_limits.1)
+        {
+            Ok(permit) => permit,
+            Err(rejection) => {
+                log_image_event(
+                    state,
+                    ctx.request_id,
+                    ctx.key,
+                    None,
+                    ctx.endpoint_name,
+                    &ctx.image_request,
+                    UpstreamLogInput {
+                        status: Some(StatusCode::TOO_MANY_REQUESTS.as_u16()),
+                        duration_ms: duration_ms(ctx.started),
+                        failover_count: 0,
+                        error_class: Some(rejection.reason),
+                        response_image_count: None,
+                        response_image_bytes: None,
+                        usage_tokens: None,
+                        usage_missing: true,
+                    },
+                );
+                return image_key_limit_response(&rejection);
+            },
+        };
     let mut failover_count = 0_u64;
     let mut concurrency_blocked = 0_usize;
     let mut last_error_class = None::<String>;
@@ -268,24 +337,28 @@ async fn dispatch_image_request(
             last_error_class = Some("auth_missing".to_string());
             continue;
         };
-        if access_token_expired(&route.auth_json) {
+        let auth = match parse_codex_image_auth(&route.auth_json) {
+            Ok(auth) => auth,
+            Err(error_class) => {
+                failover_count += 1;
+                last_error_class = Some(error_class.to_string());
+                continue;
+            },
+        };
+        if access_token_expired(&auth.access_token) {
             failover_count += 1;
             last_error_class = Some("auth_expired".to_string());
             continue;
         }
-        let Some(access_token) = access_token_from_auth_json(&route.auth_json) else {
-            failover_count += 1;
-            last_error_class = Some("auth_missing".to_string());
-            continue;
-        };
         let Some(_permit) = state.limiter.try_acquire(
             &route.account_name,
             Some(route.account_codex_image_generation_max_concurrency),
         ) else {
             concurrency_blocked += 1;
+            last_error_class = Some("concurrency_blocked".to_string());
             continue;
         };
-        let client = match provider_client(route.proxy.as_ref()) {
+        let client = match provider_client_for_route(state, route.proxy.as_ref()) {
             Ok(client) => client,
             Err(err) => {
                 tracing::warn!(account = %route.account_name, error = %err, "codex image client build failed");
@@ -294,13 +367,16 @@ async fn dispatch_image_request(
                 continue;
             },
         };
-        let upstream_url = compute_codex_upstream_url(&state.upstream_base, ctx.upstream_path);
+        let upstream_url = llm_access_codex::request::compute_codex_upstream_url(
+            &state.upstream_base,
+            ctx.upstream_path,
+        );
         let request_builder = add_image_upstream_headers(
             client.post(upstream_url),
             ctx.headers,
-            &access_token,
-            account_id_from_auth_json(&route.auth_json),
-            fedramp_from_auth_json(&route.auth_json),
+            &auth.access_token,
+            auth.account_id,
+            auth.fedramp,
             &state.codex_client_version,
         )
         .body(ctx.image_request.raw.to_string());
@@ -315,7 +391,9 @@ async fn dispatch_image_request(
         };
         let status = upstream.status();
         let headers = upstream.headers().clone();
-        let bytes = match upstream.bytes().await {
+        let bytes = match limited_upstream_bytes(upstream, MAX_IMAGE_UPSTREAM_RESPONSE_BODY_BYTES)
+            .await
+        {
             Ok(bytes) => bytes,
             Err(err) => {
                 tracing::warn!(account = %route.account_name, error = %err, "codex image upstream response read failed");
@@ -324,8 +402,12 @@ async fn dispatch_image_request(
                 continue;
             },
         };
-        let metrics = response_image_metrics(&bytes);
-        let usage_tokens = usage_tokens_from_response(&bytes);
+        let response_json = serde_json::from_slice::<Value>(&bytes).ok();
+        let metrics = response_json
+            .as_ref()
+            .map(response_image_metrics)
+            .unwrap_or_default();
+        let usage_tokens = response_json.as_ref().and_then(usage_tokens_from_response);
         log_image_event(
             state,
             ctx.request_id,
@@ -355,8 +437,13 @@ async fn dispatch_image_request(
         }
         return upstream_response(status, &headers, bytes);
     }
-    let status = if concurrency_blocked > 0 {
+    let status = if concurrency_blocked > 0 && failover_count == 0 {
         StatusCode::TOO_MANY_REQUESTS
+    } else if matches!(
+        last_error_class.as_deref(),
+        Some("auth_missing" | "auth_invalid_json" | "auth_expired" | "auth")
+    ) {
+        StatusCode::SERVICE_UNAVAILABLE
     } else {
         StatusCode::BAD_GATEWAY
     };
@@ -474,6 +561,62 @@ fn provider_client(proxy: Option<&ProviderProxyConfig>) -> anyhow::Result<reqwes
     Ok(builder.build()?)
 }
 
+fn provider_client_for_route(
+    state: &AppState,
+    proxy: Option<&ProviderProxyConfig>,
+) -> anyhow::Result<reqwest::Client> {
+    let Some(proxy_config) = proxy else {
+        return Ok(state.default_client.clone());
+    };
+    let cache_key = proxy_client_key(proxy_config);
+    let mut clients = state
+        .proxy_clients
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner());
+    if let Some(client) = clients.get(&cache_key) {
+        return Ok(client.clone());
+    }
+    let client = provider_client(Some(proxy_config))?;
+    clients.insert(cache_key, client.clone());
+    Ok(client)
+}
+
+fn proxy_client_key(proxy_config: &ProviderProxyConfig) -> String {
+    format!(
+        "{}\0{}\0{}",
+        proxy_config.proxy_url,
+        proxy_config.proxy_username.as_deref().unwrap_or_default(),
+        proxy_config.proxy_password.as_deref().unwrap_or_default()
+    )
+}
+
+async fn limited_upstream_bytes(
+    mut response: reqwest::Response,
+    max_bytes: u64,
+) -> anyhow::Result<Bytes> {
+    if response
+        .content_length()
+        .is_some_and(|content_length| content_length > max_bytes)
+    {
+        return Err(anyhow!("codex image upstream response exceeds {} bytes", max_bytes));
+    }
+    let mut body = BytesMut::new();
+    while let Some(chunk) = response
+        .chunk()
+        .await
+        .context("read codex image upstream response chunk")?
+    {
+        let next_len = u64::try_from(body.len())
+            .unwrap_or(u64::MAX)
+            .saturating_add(u64::try_from(chunk.len()).unwrap_or(u64::MAX));
+        if next_len > max_bytes {
+            return Err(anyhow!("codex image upstream response exceeds {} bytes", max_bytes));
+        }
+        body.extend_from_slice(&chunk);
+    }
+    Ok(body.freeze())
+}
+
 fn upstream_response(
     status: StatusCode,
     headers: &reqwest::header::HeaderMap,
@@ -515,14 +658,16 @@ fn log_image_event(
         input_images: &input_images,
         upstream,
     });
-    if let Err(err) = state
-        .image_log
-        .lock()
-        .expect("codex image log mutex poisoned")
-        .append(&event)
-    {
-        tracing::warn!(error = %err, "codex image request log write failed");
-    }
+    let image_log = Arc::clone(&state.image_log);
+    let handle = tokio::task::spawn_blocking(move || {
+        let mut writer = image_log
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        if let Err(err) = writer.append(&event) {
+            tracing::warn!(error = %err, "codex image request log write failed");
+        }
+    });
+    drop(handle);
 }
 
 #[derive(Debug, Default)]
@@ -531,10 +676,7 @@ struct ImageResponseMetrics {
     image_bytes: Option<u64>,
 }
 
-fn response_image_metrics(bytes: &[u8]) -> ImageResponseMetrics {
-    let Ok(value) = serde_json::from_slice::<Value>(bytes) else {
-        return ImageResponseMetrics::default();
-    };
+fn response_image_metrics(value: &Value) -> ImageResponseMetrics {
     let Some(items) = value.get("data").and_then(Value::as_array) else {
         return ImageResponseMetrics::default();
     };
@@ -550,8 +692,7 @@ fn response_image_metrics(bytes: &[u8]) -> ImageResponseMetrics {
     }
 }
 
-fn usage_tokens_from_response(bytes: &[u8]) -> Option<u64> {
-    let value = serde_json::from_slice::<Value>(bytes).ok()?;
+fn usage_tokens_from_response(value: &Value) -> Option<u64> {
     value
         .pointer("/usage/total_tokens")
         .and_then(Value::as_u64)
@@ -563,36 +704,40 @@ fn approx_base64_bytes(value: &str) -> u64 {
     ((value.len() as u64).saturating_mul(3) / 4).saturating_sub(padding)
 }
 
-fn access_token_from_auth_json(auth_json: &str) -> Option<String> {
-    let value = serde_json::from_str::<Value>(auth_json).ok()?;
-    json_string_any(&value, &["access_token", "accessToken"]).or_else(|| {
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct CodexImageAuth {
+    access_token: String,
+    account_id: Option<String>,
+    fedramp: bool,
+}
+
+fn parse_codex_image_auth(auth_json: &str) -> Result<CodexImageAuth, &'static str> {
+    let value = serde_json::from_str::<Value>(auth_json).map_err(|_| "auth_invalid_json")?;
+    let access_token = json_string_any(&value, &["access_token", "accessToken"]).or_else(|| {
         value
             .get("tokens")
             .and_then(|tokens| json_string_any(tokens, &["access_token", "accessToken"]))
-    })
-}
-
-fn account_id_from_auth_json(auth_json: &str) -> Option<String> {
-    let value = serde_json::from_str::<Value>(auth_json).ok()?;
-    json_string_any(&value, &["account_id", "accountId"]).or_else(|| {
+    });
+    let Some(access_token) = access_token else {
+        return Err("auth_missing");
+    };
+    let account_id = json_string_any(&value, &["account_id", "accountId"]).or_else(|| {
         value
             .get("account")
             .and_then(|account| json_string_any(account, &["id", "account_id", "accountId"]))
+    });
+    let fedramp = value
+        .get("is_fedramp_account")
+        .or_else(|| value.get("isFedrampAccount"))
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+    Ok(CodexImageAuth {
+        access_token,
+        account_id,
+        fedramp,
     })
 }
 
-fn fedramp_from_auth_json(auth_json: &str) -> bool {
-    serde_json::from_str::<Value>(auth_json)
-        .ok()
-        .and_then(|value| {
-            value
-                .get("is_fedramp_account")
-                .or_else(|| value.get("isFedrampAccount"))
-                .and_then(Value::as_bool)
-        })
-        .unwrap_or(false)
-}
-
 fn json_string_any(value: &Value, keys: &[&str]) -> Option<String> {
     keys.iter()
         .find_map(|key| value.get(*key).and_then(Value::as_str))
@@ -601,8 +746,8 @@ fn json_string_any(value: &Value, keys: &[&str]) -> Option<String> {
         .map(ToString::to_string)
 }
 
-fn access_token_expired(auth_json: &str) -> bool {
-    codex_auth_access_token_expires_at_ms(auth_json)
+fn access_token_expired(access_token: &str) -> bool {
+    codex_access_token_expires_at_ms(Some(access_token))
         .is_some_and(|expires_at| i64::try_from(now_ms()).unwrap_or(i64::MAX) >= expires_at)
 }
 
@@ -633,37 +778,8 @@ fn header_value(headers: &HeaderMap, name: &str) -> Option<String> {
         .map(ToString::to_string)
 }
 
-fn codex_upstream_base_url() -> String {
-    std::env::var("CODEX_UPSTREAM_BASE_URL")
-        .or_else(|_| std::env::var("STATICFLOW_LLM_GATEWAY_UPSTREAM_BASE_URL"))
-        .map(|value| llm_access_codex::request::normalize_upstream_base_url(&value))
-        .unwrap_or_else(|_| DEFAULT_UPSTREAM_BASE_URL.to_string())
-}
-
-fn compute_codex_upstream_url(base: &str, path: &str) -> String {
-    let base = base.trim_end_matches('/');
-    if base.contains("/backend-api/codex") && path.starts_with("/v1/") {
-        format!("{}{}", base, path.trim_start_matches("/v1"))
-    } else if base.ends_with("/v1") && path.starts_with("/v1") {
-        format!("{}{}", base.trim_end_matches("/v1"), path)
-    } else {
-        format!("{base}{path}")
-    }
-}
-
-fn normalize_codex_client_version(raw: &str) -> Option<String> {
-    let trimmed = raw.trim();
-    if trimmed.is_empty() || trimmed.len() > 64 {
-        return None;
-    }
-    trimmed
-        .chars()
-        .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_'))
-        .then(|| trimmed.to_string())
-}
-
 fn codex_user_agent(client_version: &str) -> String {
-    format!("codex_cli_rs/{client_version}")
+    llm_access_codex::request::codex_user_agent(client_version)
 }
 
 fn status_error_class(status: StatusCode) -> &'static str {
@@ -701,3 +817,118 @@ fn now_ms() -> u64 {
         .map(|duration| duration.as_millis() as u64)
         .unwrap_or(0)
 }
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn codex_image_auth_parser_accepts_flat_and_nested_shapes() {
+        let flat = parse_codex_image_auth(
+            r#"{
+                "accessToken": " token-a ",
+                "accountId": "acct-a",
+                "isFedrampAccount": true
+            }"#,
+        )
+        .expect("flat auth json");
+        assert_eq!(flat.access_token, "token-a");
+        assert_eq!(flat.account_id.as_deref(), Some("acct-a"));
+        assert!(flat.fedramp);
+
+        let nested = parse_codex_image_auth(
+            r#"{
+                "tokens": { "access_token": "token-b" },
+                "account": { "id": "acct-b" }
+            }"#,
+        )
+        .expect("nested auth json");
+        assert_eq!(nested.access_token, "token-b");
+        assert_eq!(nested.account_id.as_deref(), Some("acct-b"));
+        assert!(!nested.fedramp);
+
+        assert_eq!(parse_codex_image_auth(r#"{"accountId":"acct"}"#).unwrap_err(), "auth_missing");
+        assert_eq!(parse_codex_image_auth("not-json").unwrap_err(), "auth_invalid_json");
+    }
+
+    #[test]
+    fn response_metrics_and_usage_share_one_parsed_json_value() {
+        let value = json!({
+            "data": [
+                { "b64_json": "QUJDRA==" },
+                { "b64_json": "QUI=" }
+            ],
+            "usage": { "total_tokens": 42 }
+        });
+
+        let metrics = response_image_metrics(&value);
+        assert_eq!(metrics.image_count, Some(2));
+        assert_eq!(metrics.image_bytes, Some(6));
+        assert_eq!(usage_tokens_from_response(&value), Some(42));
+    }
+
+    #[test]
+    fn image_request_header_helpers_are_strict() {
+        let mut headers = HeaderMap::new();
+        assert!(!is_json_request(&headers));
+        headers.insert(header::CONTENT_TYPE, "application/json; charset=utf-8".parse().unwrap());
+        assert!(is_json_request(&headers));
+
+        assert_eq!(bearer_secret(&headers), None);
+        headers.insert(header::AUTHORIZATION, "Bearer secret-1".parse().unwrap());
+        assert_eq!(bearer_secret(&headers), Some("secret-1"));
+        headers.insert(header::AUTHORIZATION, "Basic secret-1".parse().unwrap());
+        assert_eq!(bearer_secret(&headers), None);
+    }
+
+    #[test]
+    fn reject_key_enforces_status_provider_and_quota_gate() {
+        let active = AuthenticatedKey {
+            key_id: "key-1".to_string(),
+            key_name: "Key One".to_string(),
+            provider_type: "codex".to_string(),
+            protocol_family: "openai".to_string(),
+            status: KEY_STATUS_ACTIVE.to_string(),
+            quota_billable_limit: 10,
+            billable_tokens_used: 0,
+        };
+        assert!(reject_key(&active).is_none());
+
+        let mut disabled = active.clone();
+        disabled.status = "disabled".to_string();
+        assert!(reject_key(&disabled).is_some());
+
+        let mut wrong_provider = active.clone();
+        wrong_provider.provider_type = "kiro".to_string();
+        assert!(reject_key(&wrong_provider).is_some());
+
+        let mut exhausted = active;
+        exhausted.billable_tokens_used = 10;
+        assert!(reject_key(&exhausted).is_some());
+    }
+
+    #[test]
+    fn shared_codex_upstream_helpers_cover_backend_and_v1_bases() {
+        assert_eq!(
+            llm_access_codex::request::compute_codex_upstream_url(
+                "https://chatgpt.com/backend-api/codex",
+                "/v1/images/generations",
+            ),
+            "https://chatgpt.com/backend-api/codex/images/generations"
+        );
+        assert_eq!(
+            llm_access_codex::request::compute_codex_upstream_url(
+                "https://api.example.com/v1",
+                "/v1/images/edits",
+            ),
+            "https://api.example.com/v1/images/edits"
+        );
+        assert_eq!(
+            llm_access_codex::request::normalize_codex_client_version(" 0.142.0 "),
+            Some("0.142.0".to_string())
+        );
+        assert_eq!(codex_user_agent("0.142.0"), "codex_cli_rs/0.142.0");
+    }
+}
diff --git a/crates/llm-access-codex-image/tests/codex_image_dispatch.rs b/crates/llm-access-codex-image/tests/codex_image_dispatch.rs
index df60a3bb..31c4f00a 100644
--- a/crates/llm-access-codex-image/tests/codex_image_dispatch.rs
+++ b/crates/llm-access-codex-image/tests/codex_image_dispatch.rs
@@ -3,7 +3,9 @@
 use axum::http::StatusCode;
 use llm_access_codex_image::{
     dispatch::{eligible_image_routes, should_failover_status},
-    limiter::{image_account_limiter_scope, ImageAccountLimiter},
+    limiter::{
+        image_account_limiter_scope, image_key_limiter_scope, ImageAccountLimiter, ImageKeyLimiter,
+    },
     logging::{build_image_log_event, ImageLogInput, UpstreamLogInput},
 };
 use llm_access_core::{provider::RouteStrategy, store::ProviderCodexRoute};
@@ -89,12 +91,39 @@ async fn image_account_limiter_honors_lowered_account_limit() {
 #[test]
 fn image_failover_only_retries_transient_or_auth_failures() {
     assert!(!should_failover_status(StatusCode::BAD_REQUEST));
+    assert!(!should_failover_status(StatusCode::NOT_FOUND));
+    assert!(!should_failover_status(StatusCode::UNPROCESSABLE_ENTITY));
     assert!(should_failover_status(StatusCode::UNAUTHORIZED));
     assert!(should_failover_status(StatusCode::FORBIDDEN));
     assert!(should_failover_status(StatusCode::TOO_MANY_REQUESTS));
+    assert!(should_failover_status(StatusCode::INTERNAL_SERVER_ERROR));
+    assert!(should_failover_status(StatusCode::SERVICE_UNAVAILABLE));
     assert!(should_failover_status(StatusCode::BAD_GATEWAY));
 }
 
+#[tokio::test]
+async fn image_key_limiter_uses_independent_scope_and_route_limits() {
+    assert_eq!(image_key_limiter_scope("key-1"), "key:codex-image:key-1");
+
+    let limiter = ImageKeyLimiter::default();
+    let first = limiter
+        .try_acquire("key-1", Some(1), None)
+        .expect("first key permit should be available");
+    let blocked = limiter
+        .try_acquire("key-1", Some(1), None)
+        .expect_err("key max concurrency should block");
+    assert_eq!(blocked.reason, "key_max_concurrency");
+    drop(first);
+
+    limiter
+        .try_acquire("key-2", None, Some(60_000))
+        .expect("first interval permit should be available");
+    let blocked = limiter
+        .try_acquire("key-2", None, Some(60_000))
+        .expect_err("key min start interval should block");
+    assert_eq!(blocked.reason, "key_min_start_interval");
+}
+
 #[test]
 fn image_log_event_redacts_prompt_and_image_payloads() {
     let event = build_image_log_event(ImageLogInput {
@@ -123,6 +152,8 @@ fn image_log_event_redacts_prompt_and_image_payloads() {
 
     assert!(!encoded.contains("AAABBBCCC"));
     assert!(!encoded.contains("data:image"));
+    assert!(!encoded.contains("example.com"));
+    assert!(!encoded.contains("input.png"));
     assert!(!encoded.contains("confidential text"));
     assert!(encoded.contains("prompt_hash"));
     assert!(encoded.contains("input_image_count"));
diff --git a/crates/llm-access-codex-image/tests/codex_image_request.rs b/crates/llm-access-codex-image/tests/codex_image_request.rs
index b94a38ea..3fa047ef 100644
--- a/crates/llm-access-codex-image/tests/codex_image_request.rs
+++ b/crates/llm-access-codex-image/tests/codex_image_request.rs
@@ -7,19 +7,26 @@ use serde_json::json;
 
 #[test]
 fn codex_image_path_normalization_accepts_public_aliases() {
-    assert_eq!(
-        normalize_image_gateway_path("/v1/images/generations"),
-        Some(CodexImageEndpoint::Generations)
-    );
-    assert_eq!(
-        normalize_image_gateway_path("/api/codex-gateway/images/edits"),
-        Some(CodexImageEndpoint::Edits)
-    );
-    assert_eq!(
-        normalize_image_gateway_path("/api/llm-gateway/v1/images/generations"),
-        Some(CodexImageEndpoint::Generations)
-    );
-    assert_eq!(normalize_image_gateway_path("/v1/responses"), None);
+    for (path, endpoint) in [
+        ("/v1/images/generations", CodexImageEndpoint::Generations),
+        ("/api/codex-gateway/images/generations", CodexImageEndpoint::Generations),
+        ("/api/codex-gateway/v1/images/generations", CodexImageEndpoint::Generations),
+        ("/api/llm-gateway/v1/images/generations", CodexImageEndpoint::Generations),
+        ("/v1/images/edits", CodexImageEndpoint::Edits),
+        ("/api/codex-gateway/images/edits", CodexImageEndpoint::Edits),
+        ("/api/codex-gateway/v1/images/edits", CodexImageEndpoint::Edits),
+        ("/api/llm-gateway/v1/images/edits", CodexImageEndpoint::Edits),
+    ] {
+        assert_eq!(normalize_image_gateway_path(path), Some(endpoint), "{path}");
+    }
+    for path in [
+        "/v1/responses",
+        "/v1/images/generations/",
+        "/V1/images/generations",
+        "/api/llm-gateway/images/generations",
+    ] {
+        assert_eq!(normalize_image_gateway_path(path), None, "{path}");
+    }
 }
 
 #[test]
diff --git a/crates/llm-access-codex/src/request/mod.rs b/crates/llm-access-codex/src/request/mod.rs
index 907254a8..f4603428 100644
--- a/crates/llm-access-codex/src/request/mod.rs
+++ b/crates/llm-access-codex/src/request/mod.rs
@@ -32,7 +32,11 @@ pub use headers::{
     serialize_headers_json,
 };
 pub use last_message::extract_last_message_content;
-pub use normalization::normalize_upstream_base_url;
+pub use normalization::{
+    codex_upstream_base_url_from_env, codex_user_agent, compute_codex_upstream_url,
+    normalize_codex_client_version, normalize_upstream_base_url, DEFAULT_CODEX_UPSTREAM_BASE_URL,
+    DEFAULT_CODEX_WIRE_ORIGINATOR,
+};
 pub use policy::{
     align_responses_store_with_upstream, apply_codex_fast_policy, apply_gpt53_codex_spark_mapping,
 };
diff --git a/crates/llm-access-codex/src/request/normalization.rs b/crates/llm-access-codex/src/request/normalization.rs
index 05241ad2..65f2a9d5 100644
--- a/crates/llm-access-codex/src/request/normalization.rs
+++ b/crates/llm-access-codex/src/request/normalization.rs
@@ -13,6 +13,13 @@ use crate::{
     error::{bad_request, internal_error, CodexGatewayResult},
     instructions::codex_default_instructions,
 };
+
+/// Default Codex upstream base used by StaticFlow deployments.
+pub const DEFAULT_CODEX_UPSTREAM_BASE_URL: &str = "https://chatgpt.com/backend-api/codex";
+/// Default Codex wire originator/user-agent prefix.
+pub const DEFAULT_CODEX_WIRE_ORIGINATOR: &str = "codex_cli_rs";
+const MAX_CODEX_CLIENT_VERSION_LEN: usize = 64;
+
 /// Rewrite chat/completions requests onto the upstream responses endpoint.
 pub fn rewrite_responses_path(path: &str, query: &str) -> String {
     let rewritten = if let Some(suffix) = path.strip_prefix("/v1/chat/completions") {
@@ -33,6 +40,44 @@ pub fn normalize_upstream_base_url(base: &str) -> String {
     }
     normalized
 }
+/// Resolve the configured Codex upstream base URL from supported environment
+/// variables.
+pub fn codex_upstream_base_url_from_env() -> String {
+    std::env::var("CODEX_UPSTREAM_BASE_URL")
+        .or_else(|_| std::env::var("STATICFLOW_LLM_GATEWAY_UPSTREAM_BASE_URL"))
+        .map(|value| normalize_upstream_base_url(&value))
+        .unwrap_or_else(|_| DEFAULT_CODEX_UPSTREAM_BASE_URL.to_string())
+}
+
+/// Join a normalized Codex upstream base with a public OpenAI-compatible path.
+pub fn compute_codex_upstream_url(base: &str, path: &str) -> String {
+    let base = base.trim_end_matches('/');
+    if base.contains("/backend-api/codex") && path.starts_with("/v1/") {
+        format!("{}{}", base, path.trim_start_matches("/v1"))
+    } else if base.ends_with("/v1") && path.starts_with("/v1") {
+        format!("{}{}", base.trim_end_matches("/v1"), path)
+    } else {
+        format!("{base}{path}")
+    }
+}
+
+/// Validate and normalize the Codex client version used in wire headers.
+pub fn normalize_codex_client_version(raw: &str) -> Option<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() || trimmed.len() > MAX_CODEX_CLIENT_VERSION_LEN {
+        return None;
+    }
+    trimmed
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_'))
+        .then(|| trimmed.to_string())
+}
+
+/// Build the Codex user-agent value for a normalized client version.
+pub fn codex_user_agent(client_version: &str) -> String {
+    format!("{DEFAULT_CODEX_WIRE_ORIGINATOR}/{client_version}")
+}
+
 /// Detect whether an upstream base URL points at an Azure OpenAI deployment.
 ///
 /// Azure's `/responses` surface differs from chatgpt.com (notably it persists
@@ -409,3 +454,27 @@ pub fn normalize_responses_request(
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn codex_upstream_url_helpers_cover_backend_and_v1_bases() {
+        assert_eq!(
+            normalize_upstream_base_url("https://chatgpt.com"),
+            DEFAULT_CODEX_UPSTREAM_BASE_URL
+        );
+        assert_eq!(
+            compute_codex_upstream_url(DEFAULT_CODEX_UPSTREAM_BASE_URL, "/v1/responses"),
+            "https://chatgpt.com/backend-api/codex/responses"
+        );
+        assert_eq!(
+            compute_codex_upstream_url("https://api.example.com/v1", "/v1/responses"),
+            "https://api.example.com/v1/responses"
+        );
+        assert_eq!(normalize_codex_client_version(" 0.142.0 "), Some("0.142.0".to_string()));
+        assert_eq!(normalize_codex_client_version("bad version"), None);
+        assert_eq!(codex_user_agent("0.142.0"), "codex_cli_rs/0.142.0");
+    }
+}
diff --git a/crates/llm-access-migrations/migrations/postgres/0001_init.sql b/crates/llm-access-migrations/migrations/postgres/0001_init.sql
index ec942df2..75c54ff5 100644
--- a/crates/llm-access-migrations/migrations/postgres/0001_init.sql
+++ b/crates/llm-access-migrations/migrations/postgres/0001_init.sql
@@ -29,7 +29,6 @@ CREATE TABLE IF NOT EXISTS llm_key_route_config (
     request_max_concurrency BIGINT,
     request_min_start_interval_ms BIGINT,
     codex_fast_enabled BOOLEAN NOT NULL DEFAULT TRUE,
-    codex_image_generation_enabled BOOLEAN NOT NULL DEFAULT FALSE,
     kiro_request_validation_enabled BOOLEAN NOT NULL DEFAULT FALSE,
     kiro_cache_estimation_enabled BOOLEAN NOT NULL DEFAULT FALSE,
     kiro_zero_cache_debug_enabled BOOLEAN NOT NULL DEFAULT FALSE,
diff --git a/crates/llm-access-migrations/src/lib.rs b/crates/llm-access-migrations/src/lib.rs
index a7e4de91..bfcbc13a 100644
--- a/crates/llm-access-migrations/src/lib.rs
+++ b/crates/llm-access-migrations/src/lib.rs
@@ -494,4 +494,17 @@ mod tests {
             .contains("codex_strict_session_rejection_enabled"));
         assert!(migration.sql.contains("DEFAULT FALSE"));
     }
+
+    #[test]
+    fn postgres_migrations_include_codex_image_generation_toggle() {
+        let migrations = super::postgres_migrations();
+        let migration = migrations
+            .iter()
+            .find(|migration| migration.name == "codex_image_generation_toggle")
+            .expect("codex image generation migration exists");
+
+        assert_eq!(migration.version, 30);
+        assert!(migration.sql.contains("codex_image_generation_enabled"));
+        assert!(migration.sql.contains("DEFAULT FALSE"));
+    }
 }
diff --git a/crates/llm-access-store/src/postgres.rs b/crates/llm-access-store/src/postgres.rs
index 59a8fa9a..b9c9c36a 100644
--- a/crates/llm-access-store/src/postgres.rs
+++ b/crates/llm-access-store/src/postgres.rs
@@ -519,6 +519,32 @@ impl PostgresControlRepository {
         Self::from_sqlx_client(client, request_cache_config, ProxyConfigScope::core())
     }
 
+    /// Verify that read-only Codex image gateway columns have already been
+    /// migrated.
+    pub async fn verify_codex_image_gateway_schema(&self) -> anyhow::Result<()> {
+        let row = self
+            .client
+            .query_one(
+                "SELECT EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_schema = 'public'
+                      AND table_name = 'llm_key_route_config'
+                      AND column_name = 'codex_image_generation_enabled'
+                ) AS exists",
+                &[],
+            )
+            .await
+            .context("inspect codex image gateway schema")?;
+        let exists: bool = row.get("exists");
+        anyhow::ensure!(
+            exists,
+            "missing llm_key_route_config.codex_image_generation_enabled; run llm-access Postgres \
+             migration 0030 before starting llm-access-codex-image"
+        );
+        Ok(())
+    }
+
     fn from_sqlx_client(
         client: SqlxClient,
         request_cache_config: Option<RequestCacheConfig>,
diff --git a/crates/llm-access/src/provider.rs b/crates/llm-access/src/provider.rs
index 45e5cbec..1c718d54 100644
--- a/crates/llm-access/src/provider.rs
+++ b/crates/llm-access/src/provider.rs
@@ -119,7 +119,6 @@ use crate::{
 
 const MAX_PROVIDER_PROXY_BODY_BYTES: usize = 32 * 1024 * 1024;
 const DEFAULT_WIRE_ORIGINATOR: &str = "codex_cli_rs";
-const MAX_CODEX_CLIENT_VERSION_LEN: usize = 64;
 const KIRO_PROVIDER_AWS_SDK_VERSION: &str = "1.0.34";
 const KIRO_REMOTE_IMAGE_MAX_BYTES: usize = 1_000_000;
 const KIRO_REMOTE_DOCUMENT_MAX_BYTES: usize = 8 * 1024 * 1024;
diff --git a/crates/llm-access/src/provider/codex_auth.rs b/crates/llm-access/src/provider/codex_auth.rs
index 37694571..54347468 100644
--- a/crates/llm-access/src/provider/codex_auth.rs
+++ b/crates/llm-access/src/provider/codex_auth.rs
@@ -14,7 +14,6 @@ use serde_json::Value;
 use super::{
     CodexAffinityRuntimeConfig, CodexAuthSnapshot, CodexDispatchRuntimeConfig,
     CodexTurnMetadataHeader, CodexUpstreamSessionHeaders, DEFAULT_WIRE_ORIGINATOR,
-    MAX_CODEX_CLIENT_VERSION_LEN,
 };
 
 pub fn normalized_codex_gateway_path(path: &str) -> Option<&str> {
@@ -48,33 +47,13 @@ pub fn codex_protocol_family_for_endpoint(endpoint: &str) -> ProtocolFamily {
     }
 }
 pub(crate) fn codex_upstream_base_url() -> String {
-    std::env::var("CODEX_UPSTREAM_BASE_URL")
-        .or_else(|_| std::env::var("STATICFLOW_LLM_GATEWAY_UPSTREAM_BASE_URL"))
-        .map(|value| llm_access_codex::request::normalize_upstream_base_url(&value))
-        .unwrap_or_else(|_| "https://chatgpt.com/backend-api/codex".to_string())
+    llm_access_codex::request::codex_upstream_base_url_from_env()
 }
 pub(crate) fn compute_codex_upstream_url(base: &str, path: &str) -> String {
-    let base = base.trim_end_matches('/');
-    if base.contains("/backend-api/codex") && path.starts_with("/v1/") {
-        format!("{}{}", base, path.trim_start_matches("/v1"))
-    } else if base.ends_with("/v1") && path.starts_with("/v1") {
-        format!("{}{}", base.trim_end_matches("/v1"), path)
-    } else {
-        format!("{base}{path}")
-    }
+    llm_access_codex::request::compute_codex_upstream_url(base, path)
 }
 pub fn normalize_codex_client_version(raw: &str) -> Option<String> {
-    let trimmed = raw.trim();
-    if trimmed.is_empty() || trimmed.len() > MAX_CODEX_CLIENT_VERSION_LEN {
-        return None;
-    }
-    if !trimmed
-        .chars()
-        .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_'))
-    {
-        return None;
-    }
-    Some(trimmed.to_string())
+    llm_access_codex::request::normalize_codex_client_version(raw)
 }
 pub(crate) fn resolve_codex_client_version(raw: Option<&str>) -> String {
     raw.and_then(normalize_codex_client_version)
@@ -100,7 +79,7 @@ pub async fn load_codex_dispatch_runtime_config(
     }
 }
 pub fn codex_user_agent(client_version: &str) -> String {
-    format!("{DEFAULT_WIRE_ORIGINATOR}/{client_version}")
+    llm_access_codex::request::codex_user_agent(client_version)
 }
 pub fn header_value(headers: &HeaderMap, name: &str) -> Option<String> {
     headers
diff --git a/deployment-examples/systemd/llm-access-codex-image.service.template b/deployment-examples/systemd/llm-access-codex-image.service.template
index d4b9bb4b..36ea7ea5 100644
--- a/deployment-examples/systemd/llm-access-codex-image.service.template
+++ b/deployment-examples/systemd/llm-access-codex-image.service.template
@@ -9,6 +9,8 @@ Type=simple
 User=ts_user
 Group=ts_user
 TimeoutStartSec=120
+# Requires llm-access Postgres migration 0030 before start; the binary fails
+# fast if llm_key_route_config.codex_image_generation_enabled is missing.
 EnvironmentFile=/etc/llm-access/llm-access.env
 Environment=STATICFLOW_LOG_DIR=/var/log/staticflow-runtime
 Environment=STATICFLOW_LOG_SERVICE=llm-access-codex-image
@@ -20,6 +22,8 @@ RestartSec=3
 NoNewPrivileges=true
 StateDirectory=staticflow/llm-access
 MemoryAccounting=yes
+# Upstream image responses are capped in-process; revisit this limit if
+# MAX_IMAGE_UPSTREAM_RESPONSE_BODY_BYTES or account concurrency changes.
 MemoryHigh=768M
 MemoryMax=1024M
 MemorySwapMax=256M
diff --git a/scripts/activate_llm_access_cloud_release.sh b/scripts/activate_llm_access_cloud_release.sh
index d797b659..9da278f4 100755
--- a/scripts/activate_llm_access_cloud_release.sh
+++ b/scripts/activate_llm_access_cloud_release.sh
@@ -258,10 +258,12 @@ fi
 systemctl is-active juicefs-llm-access.service >/dev/null || fail "juicefs-llm-access.service is not active"
 findmnt -T /mnt/llm-access >/dev/null || fail "/mnt/llm-access is not mounted"
 sudo install -d -m 0755 "$BACKUP_DIR"
-if [[ -e "$STAGED_NEON_ENV" ]]; then
+if [[ "$ACTIVATE_TARGET" == "image" && -e "$STAGED_NEON_ENV" ]]; then
+  log "skipping staged shared runtime env install for image-only activation"
+elif [[ -e "$STAGED_NEON_ENV" ]]; then
   [[ -r "$STAGED_NEON_ENV" ]] || fail "staged llm-access runtime env is not readable: $STAGED_NEON_ENV"
   require_env_file_var "$STAGED_NEON_ENV" LLM_ACCESS_CONTROL_DATABASE_URL "staged llm-access runtime env"
-  if [[ "$ACTIVATE_TARGET" == "image" ]]; then
+  if [[ "$ACTIVATE_TARGET" == "both" ]]; then
     require_env_file_var "$STAGED_NEON_ENV" LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL "staged llm-access runtime env"
   fi
   require_env_file_var "$STAGED_NEON_ENV" KIRO_THINKING_SIGNATURE_SECRET "staged llm-access runtime env"
@@ -322,7 +324,7 @@ installed_sha=""
 installed_worker_sha=""
 installed_image_sha=""
 
-if [[ -e "$STAGED_NEON_ENV" && -e "$BACKUP_DIR/neon.env.preinstall" ]]; then
+if [[ "$ACTIVATE_TARGET" != "image" && -e "$STAGED_NEON_ENV" && -e "$BACKUP_DIR/neon.env.preinstall" ]]; then
   sudo mv "$BACKUP_DIR/neon.env.preinstall" "$neon_env_backup_path"
 fi
 
diff --git a/scripts/prepare_llm_access_cloud_release.sh b/scripts/prepare_llm_access_cloud_release.sh
index 8f4af54e..08f4d27f 100755
--- a/scripts/prepare_llm_access_cloud_release.sh
+++ b/scripts/prepare_llm_access_cloud_release.sh
@@ -92,6 +92,13 @@ load_config
 
 BUILD_JOBS="${BUILD_JOBS:-4}"
 ALLOW_DIRTY="${ALLOW_DIRTY:-0}"
+PREPARE_TARGET="${LLM_ACCESS_ACTIVATE_TARGET:-both}"
+case "$PREPARE_TARGET" in
+  api | worker | image | both) ;;
+  *)
+    fail "unsupported prepare target: $PREPARE_TARGET (expected api, worker, image, or both)"
+    ;;
+esac
 require_var CARGO_TARGET_DIR
 require_var GCP_SSH_KEY
 require_var REMOTE_RELEASE_DIR
@@ -111,7 +118,9 @@ LOCAL_NEON_ENV_FILE="$(expand_path "$LOCAL_NEON_ENV_FILE")"
 [[ -r "$GCP_SSH_KEY" ]] || fail "SSH key is not readable: $GCP_SSH_KEY"
 [[ -r "$LOCAL_NEON_ENV_FILE" ]] || fail "local llm-access runtime env is not readable: $LOCAL_NEON_ENV_FILE"
 require_env_file_var "$LOCAL_NEON_ENV_FILE" LLM_ACCESS_CONTROL_DATABASE_URL "local llm-access runtime env"
-require_env_file_var "$LOCAL_NEON_ENV_FILE" LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL "local llm-access runtime env"
+if [[ "$PREPARE_TARGET" == "image" || "$PREPARE_TARGET" == "both" ]]; then
+  require_env_file_var "$LOCAL_NEON_ENV_FILE" LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL "local llm-access runtime env"
+fi
 require_env_file_var "$LOCAL_NEON_ENV_FILE" KIRO_THINKING_SIGNATURE_SECRET "local llm-access runtime env"
 
 cd "$ROOT_DIR"
diff --git a/scripts/release_llm_access_cloud_api_only.sh b/scripts/release_llm_access_cloud_api_only.sh
index dc3f1fb6..7a5f8fd3 100755
--- a/scripts/release_llm_access_cloud_api_only.sh
+++ b/scripts/release_llm_access_cloud_api_only.sh
@@ -63,7 +63,7 @@ fi
 GCP_SSH_KEY="$(expand_path "$GCP_SSH_KEY")"
 SSH_OPTS=(-i "$GCP_SSH_KEY" -o IdentitiesOnly=yes -o BatchMode=yes)
 
-"$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
+LLM_ACCESS_ACTIVATE_TARGET=api "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
 "$ROOT_DIR/scripts/render_llm_access_cloud_bundle.sh" "$RENDER_DIR"
 
 scp "${SSH_OPTS[@]}" \
diff --git a/scripts/release_llm_access_cloud_codex_image_only.sh b/scripts/release_llm_access_cloud_codex_image_only.sh
index ef248007..9cc95e23 100755
--- a/scripts/release_llm_access_cloud_codex_image_only.sh
+++ b/scripts/release_llm_access_cloud_codex_image_only.sh
@@ -63,7 +63,9 @@ fi
 GCP_SSH_KEY="$(expand_path "$GCP_SSH_KEY")"
 SSH_OPTS=(-i "$GCP_SSH_KEY" -o IdentitiesOnly=yes -o BatchMode=yes)
 
-"$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
+# The image gateway is read-only against Postgres. Apply llm-access migration
+# 0030 from the control-plane service before activating this binary.
+LLM_ACCESS_ACTIVATE_TARGET=image "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
 "$ROOT_DIR/scripts/render_llm_access_cloud_bundle.sh" "$RENDER_DIR"
 
 scp "${SSH_OPTS[@]}" \
diff --git a/scripts/release_llm_access_cloud_worker_only.sh b/scripts/release_llm_access_cloud_worker_only.sh
index 43b14058..6bfa5088 100755
--- a/scripts/release_llm_access_cloud_worker_only.sh
+++ b/scripts/release_llm_access_cloud_worker_only.sh
@@ -63,7 +63,7 @@ fi
 GCP_SSH_KEY="$(expand_path "$GCP_SSH_KEY")"
 SSH_OPTS=(-i "$GCP_SSH_KEY" -o IdentitiesOnly=yes -o BatchMode=yes)
 
-"$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
+LLM_ACCESS_ACTIVATE_TARGET=worker "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
 "$ROOT_DIR/scripts/render_llm_access_cloud_bundle.sh" "$RENDER_DIR"
 
 scp "${SSH_OPTS[@]}" \
diff --git a/scripts/test_llm_access_cloud_release_scripts.sh b/scripts/test_llm_access_cloud_release_scripts.sh
index bdced202..29abee51 100755
--- a/scripts/test_llm_access_cloud_release_scripts.sh
+++ b/scripts/test_llm_access_cloud_release_scripts.sh
@@ -50,15 +50,19 @@ grep -F 'KIRO_THINKING_SIGNATURE_SECRET' "$REMOTE_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL' "$LOCAL_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_CODEX_IMAGE_CONTROL_DATABASE_URL' "$REMOTE_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_ACTIVATE_TARGET=api' "$API_ONLY_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_ACTIVATE_TARGET=api "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"' "$API_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_STAGED_SERVICE_UNIT=' "$API_ONLY_SCRIPT" >/dev/null
 grep -F 'render_llm_access_cloud_bundle.sh' "$API_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_ACTIVATE_TARGET=worker' "$WORKER_ONLY_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_ACTIVATE_TARGET=worker "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"' "$WORKER_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_STAGED_WORKER_SERVICE_UNIT=' "$WORKER_ONLY_SCRIPT" >/dev/null
 grep -F 'render_llm_access_cloud_bundle.sh' "$WORKER_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_ACTIVATE_TARGET=image' "$IMAGE_ONLY_SCRIPT" >/dev/null
+grep -F 'LLM_ACCESS_ACTIVATE_TARGET=image "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"' "$IMAGE_ONLY_SCRIPT" >/dev/null
 grep -F 'LLM_ACCESS_STAGED_IMAGE_SERVICE_UNIT=' "$IMAGE_ONLY_SCRIPT" >/dev/null
 grep -F 'render_llm_access_cloud_bundle.sh' "$IMAGE_ONLY_SCRIPT" >/dev/null
 grep -F 'llm-access-codex-image.latest' "$REMOTE_SCRIPT" >/dev/null
+grep -F 'skipping staged shared runtime env install for image-only activation' "$REMOTE_SCRIPT" >/dev/null
 
 grep -F 'GCP_HOST=' "$CONFIG_EXAMPLE" >/dev/null
 grep -F 'GCP_SSH_KEY=' "$CONFIG_EXAMPLE" >/dev/null

From 2f65f8ea6ec829e10b7cc5e888b26ac3af0da316 Mon Sep 17 00:00:00 2001
From: LB7666 <acking-you@foxmail.com>
Date: Fri, 26 Jun 2026 21:43:32 +0800
Subject: [PATCH 3/3] feat(llm-access): track codex image key usage

---
 crates/frontend/src/api.rs                    | 27 ++++++
 .../frontend/src/pages/admin_llm_gateway.rs   |  8 +-
 crates/llm-access-codex-image/src/main.rs     | 27 +++++-
 crates/llm-access-core/src/store/empty.rs     |  3 +
 crates/llm-access-core/src/store/keys.rs      | 88 +++++++++++++++++++
 .../0031_codex_image_key_usage_rollup.sql     | 10 +++
 crates/llm-access-migrations/src/lib.rs       | 19 ++++
 crates/llm-access-store/src/postgres.rs       | 85 +++++++++++++++---
 .../llm-access-store/src/postgres/decode.rs   | 13 ++-
 crates/llm-access-store/src/postgres/keys.rs  | 45 +++++++++-
 crates/llm-access-store/src/postgres/usage.rs | 72 +++++++++++++++
 crates/llm-access-store/src/records.rs        |  6 ++
 crates/llm-access/src/admin.rs                |  3 +
 .../llm-access-codex-image.service.template   |  4 +-
 ...lease_llm_access_cloud_codex_image_only.sh |  5 +-
 15 files changed, 387 insertions(+), 28 deletions(-)
 create mode 100644 crates/llm-access-migrations/migrations/postgres/0031_codex_image_key_usage_rollup.sql

diff --git a/crates/frontend/src/api.rs b/crates/frontend/src/api.rs
index 0e358d45..dad0fa99 100644
--- a/crates/frontend/src/api.rs
+++ b/crates/frontend/src/api.rs
@@ -6099,6 +6099,12 @@ pub struct AdminLlmGatewayKeyView {
     pub usage_output_tokens: u64,
     pub usage_credit_total: f64,
     pub usage_credit_missing_events: u64,
+    #[serde(default)]
+    pub codex_image_usage_tokens: u64,
+    #[serde(default)]
+    pub codex_image_usage_missing_events: u64,
+    #[serde(default)]
+    pub codex_image_last_used_at: Option<i64>,
     pub remaining_billable: i64,
     pub last_used_at: Option<i64>,
     pub created_at: i64,
@@ -6176,6 +6182,10 @@ pub struct AdminLlmGatewayKeysSummaryView {
     pub usage_billable_tokens_sum: u64,
     pub usage_credit_total: f64,
     pub usage_credit_missing_events: u64,
+    #[serde(default)]
+    pub codex_image_usage_tokens_sum: u64,
+    #[serde(default)]
+    pub codex_image_usage_missing_events: u64,
 }
 
 /// Combined admin payload for the key inventory screen.
@@ -8962,6 +8972,9 @@ pub async fn create_admin_llm_gateway_key(
             usage_output_tokens: 0,
             usage_credit_total: 0.0,
             usage_credit_missing_events: 0,
+            codex_image_usage_tokens: 0,
+            codex_image_usage_missing_events: 0,
+            codex_image_last_used_at: None,
             remaining_billable: quota_billable_limit as i64,
             last_used_at: None,
             created_at: 0,
@@ -11236,6 +11249,9 @@ pub async fn create_admin_kiro_key(
             usage_output_tokens: 0,
             usage_credit_total: 0.0,
             usage_credit_missing_events: 0,
+            codex_image_usage_tokens: 0,
+            codex_image_usage_missing_events: 0,
+            codex_image_last_used_at: None,
             remaining_billable: quota_billable_limit as i64,
             last_used_at: None,
             created_at: 0,
@@ -12004,6 +12020,17 @@ mod tests {
         assert!(!key.codex_image_generation_enabled);
     }
 
+    #[test]
+    fn admin_gateway_key_view_defaults_codex_image_usage_to_zero() {
+        let key: AdminLlmGatewayKeyView =
+            serde_json::from_str(r#"{"id":"k","name":"K","provider_type":"codex"}"#)
+                .expect("key should parse");
+
+        assert_eq!(key.codex_image_usage_tokens, 0);
+        assert_eq!(key.codex_image_usage_missing_events, 0);
+        assert_eq!(key.codex_image_last_used_at, None);
+    }
+
     #[test]
     fn admin_gateway_key_page_merge_preserves_all_rows_and_latest_summary() {
         let first = AdminLlmGatewayKeysResponse {
diff --git a/crates/frontend/src/pages/admin_llm_gateway.rs b/crates/frontend/src/pages/admin_llm_gateway.rs
index 9ebf3ff1..9cbf51f2 100644
--- a/crates/frontend/src/pages/admin_llm_gateway.rs
+++ b/crates/frontend/src/pages/admin_llm_gateway.rs
@@ -1845,7 +1845,7 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
                 </span>
             </div>
 
-            <div class={classes!("mt-3", "flex", "items-center", "gap-4", "text-xs", "text-[var(--muted)]")}>
+            <div class={classes!("mt-3", "flex", "flex-wrap", "items-center", "gap-4", "text-xs", "text-[var(--muted)]")}>
                 <span>{ format!("剩余 {}", format_number_i64(key_item.remaining_billable)) }</span>
                 <span>{ format!("输入 {}", format_number_u64(key_item.usage_input_uncached_tokens)) }</span>
                 <span>{ format!("缓存 {}", format_number_u64(key_item.usage_input_cached_tokens)) }</span>
@@ -1859,6 +1859,12 @@ fn key_editor_card(props: &KeyEditorCardProps) -> Html {
                     key_item.request_min_start_interval_ms.map(|value| value.to_string()).unwrap_or_else(|| "∞".to_string())
                 ) }</span>
                 <span>{ if key_item.codex_image_generation_enabled { "生图 on" } else { "生图 off" } }</span>
+                if key_item.provider_type == "codex" {
+                    <span>{ format!("Image2 {}", format_number_u64(key_item.codex_image_usage_tokens)) }</span>
+                    if key_item.codex_image_usage_missing_events > 0 {
+                        <span>{ format!("image partial {}", key_item.codex_image_usage_missing_events) }</span>
+                    }
+                }
                 <span>{ format!("Credit {}", key_credit_display(&key_item)) }</span>
                 if key_item.usage_credit_missing_events > 0 {
                     <span>{ format!("partial {}", key_item.usage_credit_missing_events) }</span>
diff --git a/crates/llm-access-codex-image/src/main.rs b/crates/llm-access-codex-image/src/main.rs
index 4e4deb13..f822e151 100644
--- a/crates/llm-access-codex-image/src/main.rs
+++ b/crates/llm-access-codex-image/src/main.rs
@@ -105,9 +105,9 @@ async fn serve(args: ServeArgs) -> anyhow::Result<()> {
         })?;
     let request_cache_config = request_cache_config(&args)?;
     let control = Arc::new(
-        PostgresControlRepository::connect_read_only(&database_url, request_cache_config)
+        PostgresControlRepository::connect_without_migrations(&database_url, request_cache_config)
             .await
-            .context("connect read-only postgres control repository")?,
+            .context("connect postgres control repository without migrations")?,
     );
     control
         .verify_codex_image_gateway_schema()
@@ -435,6 +435,9 @@ async fn dispatch_image_request(
             last_error_class = Some(status_error_class(status).to_string());
             continue;
         }
+        if status.is_success() {
+            record_codex_image_usage(state, ctx.key, usage_tokens).await;
+        }
         return upstream_response(status, &headers, bytes);
     }
     let status = if concurrency_blocked > 0 && failover_count == 0 {
@@ -670,6 +673,26 @@ fn log_image_event(
     drop(handle);
 }
 
+async fn record_codex_image_usage(
+    state: &AppState,
+    key: &AuthenticatedKey,
+    usage_tokens: Option<u64>,
+) {
+    let used_at_ms = i64::try_from(now_ms()).unwrap_or(i64::MAX);
+    if let Err(err) = state
+        .control
+        .record_codex_image_key_usage(&key.key_id, usage_tokens, used_at_ms)
+        .await
+    {
+        tracing::warn!(
+            key_id = %key.key_id,
+            key_name = %key.key_name,
+            error = %err,
+            "codex image key usage rollup write failed"
+        );
+    }
+}
+
 #[derive(Debug, Default)]
 struct ImageResponseMetrics {
     image_count: Option<u64>,
diff --git a/crates/llm-access-core/src/store/empty.rs b/crates/llm-access-core/src/store/empty.rs
index 0356395a..b440cb3e 100644
--- a/crates/llm-access-core/src/store/empty.rs
+++ b/crates/llm-access-core/src/store/empty.rs
@@ -358,6 +358,9 @@ impl AdminKeyStore for EmptyAdminKeyStore {
             usage_output_tokens: 0,
             usage_credit_total: 0.0,
             usage_credit_missing_events: 0,
+            codex_image_usage_tokens: 0,
+            codex_image_usage_missing_events: 0,
+            codex_image_last_used_at: None,
             remaining_billable: key.quota_billable_limit as i64,
             last_used_at: None,
             created_at: key.created_at_ms,
diff --git a/crates/llm-access-core/src/store/keys.rs b/crates/llm-access-core/src/store/keys.rs
index 04a3ea2d..0b773b74 100644
--- a/crates/llm-access-core/src/store/keys.rs
+++ b/crates/llm-access-core/src/store/keys.rs
@@ -36,6 +36,15 @@ pub struct AdminKey {
     pub usage_credit_total: f64,
     /// Number of events missing credit usage.
     pub usage_credit_missing_events: u64,
+    /// Accumulated Codex image-generation tokens reported by upstream.
+    #[serde(default)]
+    pub codex_image_usage_tokens: u64,
+    /// Number of successful Codex image responses missing upstream usage.
+    #[serde(default)]
+    pub codex_image_usage_missing_events: u64,
+    /// Last successful Codex image usage timestamp.
+    #[serde(default)]
+    pub codex_image_last_used_at: Option<i64>,
     /// Remaining billable tokens.
     pub remaining_billable: i64,
     /// Last usage timestamp.
@@ -183,6 +192,10 @@ pub struct AdminKeysSummary {
     pub usage_credit_total: f64,
     /// Sum of events missing credit usage.
     pub usage_credit_missing_events: u64,
+    /// Sum of Codex image-generation tokens reported by upstream.
+    pub codex_image_usage_tokens_sum: u64,
+    /// Sum of successful Codex image responses missing upstream usage.
+    pub codex_image_usage_missing_events: u64,
 }
 
 /// Admin key list query shared by paginated inventory screens.
@@ -247,6 +260,12 @@ pub fn summarize_admin_keys(keys: &[AdminKey]) -> AdminKeysSummary {
         summary.usage_credit_missing_events = summary
             .usage_credit_missing_events
             .saturating_add(key.usage_credit_missing_events);
+        summary.codex_image_usage_tokens_sum = summary
+            .codex_image_usage_tokens_sum
+            .saturating_add(key.codex_image_usage_tokens);
+        summary.codex_image_usage_missing_events = summary
+            .codex_image_usage_missing_events
+            .saturating_add(key.codex_image_usage_missing_events);
     }
     summary
 }
@@ -380,3 +399,72 @@ pub struct AdminKeyPatch {
     /// Update timestamp.
     pub updated_at_ms: i64,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn admin_key_with_codex_image_usage(id: &str, image_tokens: u64, missing: u64) -> AdminKey {
+        AdminKey {
+            id: id.to_string(),
+            name: id.to_string(),
+            secret: "secret".to_string(),
+            key_hash: "hash".to_string(),
+            status: KEY_STATUS_ACTIVE.to_string(),
+            provider_type: "codex".to_string(),
+            public_visible: true,
+            quota_billable_limit: 1_000,
+            usage_input_uncached_tokens: 0,
+            usage_input_cached_tokens: 0,
+            usage_output_tokens: 0,
+            usage_credit_total: 0.0,
+            usage_credit_missing_events: 0,
+            codex_image_usage_tokens: image_tokens,
+            codex_image_usage_missing_events: missing,
+            codex_image_last_used_at: Some(1_700_000_000_000),
+            remaining_billable: 1_000,
+            last_used_at: None,
+            created_at: 1,
+            updated_at: 1,
+            route_strategy: None,
+            account_group_id: None,
+            fixed_account_name: None,
+            auto_account_names: None,
+            preferred_pool_strategy: "balanced".to_string(),
+            model_name_map: None,
+            request_max_concurrency: None,
+            request_min_start_interval_ms: None,
+            codex_fast_enabled: true,
+            codex_strict_session_rejection_enabled: false,
+            codex_image_generation_enabled: true,
+            kiro_request_validation_enabled: false,
+            kiro_cache_estimation_enabled: false,
+            kiro_zero_cache_debug_enabled: false,
+            kiro_full_request_logging_enabled: false,
+            kiro_remote_media_resolution_enabled: false,
+            kiro_latency_routing_enabled: true,
+            kiro_protected_content_validation_enabled: false,
+            kiro_cctest_text_handling_enabled: false,
+            kiro_cache_policy_override_json: None,
+            kiro_billable_model_multipliers_override_json: None,
+            effective_kiro_cache_policy_json: "{}".to_string(),
+            uses_global_kiro_cache_policy: true,
+            effective_kiro_billable_model_multipliers_json: "{}".to_string(),
+            uses_global_kiro_billable_model_multipliers: true,
+            kiro_candidate_credit_summary: None,
+        }
+    }
+
+    #[test]
+    fn summarize_admin_keys_accumulates_codex_image_usage() {
+        let keys = vec![
+            admin_key_with_codex_image_usage("key-a", 10, 1),
+            admin_key_with_codex_image_usage("key-b", 15, 2),
+        ];
+
+        let summary = summarize_admin_keys(&keys);
+
+        assert_eq!(summary.codex_image_usage_tokens_sum, 25);
+        assert_eq!(summary.codex_image_usage_missing_events, 3);
+    }
+}
diff --git a/crates/llm-access-migrations/migrations/postgres/0031_codex_image_key_usage_rollup.sql b/crates/llm-access-migrations/migrations/postgres/0031_codex_image_key_usage_rollup.sql
new file mode 100644
index 00000000..c3ff79fc
--- /dev/null
+++ b/crates/llm-access-migrations/migrations/postgres/0031_codex_image_key_usage_rollup.sql
@@ -0,0 +1,10 @@
+ALTER TABLE IF EXISTS llm_key_usage_rollups
+    ADD COLUMN IF NOT EXISTS codex_image_usage_tokens BIGINT NOT NULL DEFAULT 0
+        CHECK (codex_image_usage_tokens >= 0);
+
+ALTER TABLE IF EXISTS llm_key_usage_rollups
+    ADD COLUMN IF NOT EXISTS codex_image_usage_missing_events BIGINT NOT NULL DEFAULT 0
+        CHECK (codex_image_usage_missing_events >= 0);
+
+ALTER TABLE IF EXISTS llm_key_usage_rollups
+    ADD COLUMN IF NOT EXISTS codex_image_last_used_at_ms BIGINT;
diff --git a/crates/llm-access-migrations/src/lib.rs b/crates/llm-access-migrations/src/lib.rs
index bfcbc13a..b13a65f4 100644
--- a/crates/llm-access-migrations/src/lib.rs
+++ b/crates/llm-access-migrations/src/lib.rs
@@ -148,6 +148,11 @@ const POSTGRES_MIGRATIONS: &[SqlMigration] = &[
         name: "codex_image_generation_toggle",
         sql: include_str!("../migrations/postgres/0030_codex_image_generation_toggle.sql"),
     },
+    SqlMigration {
+        version: 31,
+        name: "codex_image_key_usage_rollup",
+        sql: include_str!("../migrations/postgres/0031_codex_image_key_usage_rollup.sql"),
+    },
 ];
 
 /// Return target DuckDB migrations in execution order.
@@ -507,4 +512,18 @@ mod tests {
         assert!(migration.sql.contains("codex_image_generation_enabled"));
         assert!(migration.sql.contains("DEFAULT FALSE"));
     }
+
+    #[test]
+    fn postgres_migrations_include_codex_image_key_usage_rollup() {
+        let migrations = super::postgres_migrations();
+        let migration = migrations
+            .iter()
+            .find(|migration| migration.name == "codex_image_key_usage_rollup")
+            .expect("codex image key usage rollup migration exists");
+
+        assert_eq!(migration.version, 31);
+        assert!(migration.sql.contains("codex_image_usage_tokens"));
+        assert!(migration.sql.contains("codex_image_usage_missing_events"));
+        assert!(migration.sql.contains("codex_image_last_used_at_ms"));
+    }
 }
diff --git a/crates/llm-access-store/src/postgres.rs b/crates/llm-access-store/src/postgres.rs
index b9c9c36a..c724f9b3 100644
--- a/crates/llm-access-store/src/postgres.rs
+++ b/crates/llm-access-store/src/postgres.rs
@@ -511,7 +511,7 @@ impl PostgresControlRepository {
     }
 
     /// Connect to the Postgres control plane without running migrations.
-    pub async fn connect_read_only(
+    pub async fn connect_without_migrations(
         database_url: &str,
         request_cache_config: Option<RequestCacheConfig>,
     ) -> anyhow::Result<Self> {
@@ -519,28 +519,48 @@ impl PostgresControlRepository {
         Self::from_sqlx_client(client, request_cache_config, ProxyConfigScope::core())
     }
 
-    /// Verify that read-only Codex image gateway columns have already been
-    /// migrated.
+    /// Backward-compatible alias for callers that only need read paths.
+    pub async fn connect_read_only(
+        database_url: &str,
+        request_cache_config: Option<RequestCacheConfig>,
+    ) -> anyhow::Result<Self> {
+        Self::connect_without_migrations(database_url, request_cache_config).await
+    }
+
+    /// Verify that Codex image gateway columns have already been migrated.
     pub async fn verify_codex_image_gateway_schema(&self) -> anyhow::Result<()> {
         let row = self
             .client
             .query_one(
-                "SELECT EXISTS (
-                    SELECT 1
-                    FROM information_schema.columns
-                    WHERE table_schema = 'public'
-                      AND table_name = 'llm_key_route_config'
-                      AND column_name = 'codex_image_generation_enabled'
-                ) AS exists",
+                "SELECT
+                    EXISTS (
+                        SELECT 1
+                        FROM information_schema.columns
+                        WHERE table_schema = 'public'
+                          AND table_name = 'llm_key_route_config'
+                          AND column_name = 'codex_image_generation_enabled'
+                    ) AS route_toggle_exists,
+                    (
+                        SELECT COUNT(*) = 3
+                        FROM information_schema.columns
+                        WHERE table_schema = 'public'
+                          AND table_name = 'llm_key_usage_rollups'
+                          AND column_name IN (
+                              'codex_image_usage_tokens',
+                              'codex_image_usage_missing_events',
+                              'codex_image_last_used_at_ms'
+                          )
+                    ) AS usage_rollup_exists",
                 &[],
             )
             .await
             .context("inspect codex image gateway schema")?;
-        let exists: bool = row.get("exists");
+        let route_toggle_exists: bool = row.get("route_toggle_exists");
+        let usage_rollup_exists: bool = row.get("usage_rollup_exists");
         anyhow::ensure!(
-            exists,
-            "missing llm_key_route_config.codex_image_generation_enabled; run llm-access Postgres \
-             migration 0030 before starting llm-access-codex-image"
+            route_toggle_exists && usage_rollup_exists,
+            "missing codex image gateway schema columns; run llm-access Postgres migrations 0030 \
+             and 0031 before starting llm-access-codex-image"
         );
         Ok(())
     }
@@ -1133,6 +1153,43 @@ mod tests {
         client.close().await;
     }
 
+    #[tokio::test]
+    async fn postgres_repository_records_codex_image_usage_separately() {
+        let Ok(database_url) = std::env::var("TEST_POSTGRES_URL") else {
+            eprintln!("skipping postgres integration test: TEST_POSTGRES_URL is not set");
+            return;
+        };
+        let _guard = test_db_guard().await;
+        reset_test_db(&database_url)
+            .await
+            .expect("reset postgres test database");
+        seed_test_key_bundle(&database_url)
+            .await
+            .expect("seed postgres test key bundle");
+        let repo = super::PostgresControlRepository::connect(&database_url, None)
+            .await
+            .expect("connect postgres repository");
+
+        repo.record_codex_image_key_usage("key-1", Some(42), 1_700_000_000_100)
+            .await
+            .expect("record image token usage");
+        repo.record_codex_image_key_usage("key-1", None, 1_700_000_000_120)
+            .await
+            .expect("record missing image usage");
+
+        let key = repo
+            .get_admin_key("key-1")
+            .await
+            .expect("load admin key")
+            .expect("key exists");
+        assert_eq!(key.codex_image_usage_tokens, 42);
+        assert_eq!(key.codex_image_usage_missing_events, 1);
+        assert_eq!(key.codex_image_last_used_at, Some(1_700_000_000_120));
+        assert_eq!(key.usage_input_uncached_tokens, 0);
+        assert_eq!(key.usage_output_tokens, 0);
+        assert_eq!(key.remaining_billable, 1000);
+    }
+
     #[tokio::test]
     async fn postgres_repository_accepts_legacy_json_rollup_marker_digest() {
         let Ok(database_url) = std::env::var("TEST_POSTGRES_URL") else {
diff --git a/crates/llm-access-store/src/postgres/decode.rs b/crates/llm-access-store/src/postgres/decode.rs
index 54bde2c0..1ad57a25 100644
--- a/crates/llm-access-store/src/postgres/decode.rs
+++ b/crates/llm-access-store/src/postgres/decode.rs
@@ -147,8 +147,11 @@ fn decode_key_bundle(row: &PgRow) -> anyhow::Result<KeyBundle> {
             billable_tokens: row.get(31),
             credit_total,
             credit_missing_events: row.get(33),
-            last_used_at_ms: row.get(34),
-            updated_at_ms: row.get(35),
+            codex_image_usage_tokens: row.get(34),
+            codex_image_usage_missing_events: row.get(35),
+            codex_image_last_used_at_ms: row.get(36),
+            last_used_at_ms: row.get(37),
+            updated_at_ms: row.get(38),
         },
     })
 }
@@ -174,6 +177,10 @@ pub fn admin_key_from_bundle(bundle: &KeyBundle) -> AdminKey {
         usage_output_tokens: bundle.rollup.output_tokens.max(0) as u64,
         usage_credit_total: bundle.rollup.credit_total,
         usage_credit_missing_events: bundle.rollup.credit_missing_events.max(0) as u64,
+        codex_image_usage_tokens: bundle.rollup.codex_image_usage_tokens.max(0) as u64,
+        codex_image_usage_missing_events: bundle.rollup.codex_image_usage_missing_events.max(0)
+            as u64,
+        codex_image_last_used_at: bundle.rollup.codex_image_last_used_at_ms,
         remaining_billable: (quota as i64).saturating_sub(billable as i64),
         last_used_at: bundle.rollup.last_used_at_ms,
         created_at: bundle.key.created_at_ms,
@@ -246,7 +253,7 @@ fn decode_kiro_candidate_credit_summary_row(
 pub fn decode_kiro_admin_key_row(row: PgRow) -> anyhow::Result<AdminKey> {
     let bundle = decode_key_bundle(&row)?;
     let mut key = admin_key_from_bundle(&bundle);
-    key.kiro_candidate_credit_summary = Some(decode_kiro_candidate_credit_summary_row(&row, 36));
+    key.kiro_candidate_credit_summary = Some(decode_kiro_candidate_credit_summary_row(&row, 39));
     Ok(key)
 }
 
diff --git a/crates/llm-access-store/src/postgres/keys.rs b/crates/llm-access-store/src/postgres/keys.rs
index 750fb5c7..7c983aaa 100644
--- a/crates/llm-access-store/src/postgres/keys.rs
+++ b/crates/llm-access-store/src/postgres/keys.rs
@@ -103,6 +103,9 @@ impl PostgresControlRepository {
                     COALESCE(u.billable_tokens, 0),
                     COALESCE(u.credit_total, '0'),
                     COALESCE(u.credit_missing_events, 0),
+                    COALESCE(u.codex_image_usage_tokens, 0),
+                    COALESCE(u.codex_image_usage_missing_events, 0),
+                    u.codex_image_last_used_at_ms,
                     u.last_used_at_ms,
                     COALESCE(u.updated_at_ms, 0),
                     r.preferred_pool_strategy AS preferred_pool_strategy,
@@ -148,6 +151,9 @@ impl PostgresControlRepository {
                     COALESCE(u.billable_tokens, 0),
                     COALESCE(u.credit_total, '0'),
                     COALESCE(u.credit_missing_events, 0),
+                    COALESCE(u.codex_image_usage_tokens, 0),
+                    COALESCE(u.codex_image_usage_missing_events, 0),
+                    u.codex_image_last_used_at_ms,
                     u.last_used_at_ms,
                     COALESCE(u.updated_at_ms, k.updated_at_ms),
                     r.preferred_pool_strategy AS preferred_pool_strategy,
@@ -191,7 +197,9 @@ impl PostgresControlRepository {
                     COALESCE(SUM(u.output_tokens), 0)::BIGINT,
                     COALESCE(SUM(u.billable_tokens), 0)::BIGINT,
                     COALESCE(SUM((u.credit_total)::DOUBLE PRECISION), 0)::DOUBLE PRECISION,
-                    COALESCE(SUM(u.credit_missing_events), 0)::BIGINT
+                    COALESCE(SUM(u.credit_missing_events), 0)::BIGINT,
+                    COALESCE(SUM(u.codex_image_usage_tokens), 0)::BIGINT,
+                    COALESCE(SUM(u.codex_image_usage_missing_events), 0)::BIGINT
                  FROM llm_keys k
                  LEFT JOIN llm_key_usage_rollups u ON u.key_id = k.key_id
                  WHERE ($1::text IS NULL OR k.provider_type = $1)",
@@ -212,6 +220,8 @@ impl PostgresControlRepository {
             usage_billable_tokens_sum: row.get::<_, i64>(9).max(0) as u64,
             usage_credit_total: row.get(10),
             usage_credit_missing_events: row.get::<_, i64>(11).max(0) as u64,
+            codex_image_usage_tokens_sum: row.get::<_, i64>(12).max(0) as u64,
+            codex_image_usage_missing_events: row.get::<_, i64>(13).max(0) as u64,
         })
     }
 
@@ -265,6 +275,9 @@ impl PostgresControlRepository {
                     COALESCE(u.billable_tokens, 0),
                     COALESCE(u.credit_total, '0'),
                     COALESCE(u.credit_missing_events, 0),
+                    COALESCE(u.codex_image_usage_tokens, 0),
+                    COALESCE(u.codex_image_usage_missing_events, 0),
+                    u.codex_image_last_used_at_ms,
                     u.last_used_at_ms,
                     COALESCE(u.updated_at_ms, k.updated_at_ms),
                     r.preferred_pool_strategy AS preferred_pool_strategy,
@@ -339,6 +352,10 @@ impl PostgresControlRepository {
                         COALESCE(u.billable_tokens, 0) AS billable_tokens,
                         COALESCE(u.credit_total, '0') AS credit_total,
                         COALESCE(u.credit_missing_events, 0) AS credit_missing_events,
+                        COALESCE(u.codex_image_usage_tokens, 0) AS codex_image_usage_tokens,
+                        COALESCE(u.codex_image_usage_missing_events, 0)
+                            AS codex_image_usage_missing_events,
+                        u.codex_image_last_used_at_ms,
                         u.last_used_at_ms,
                         COALESCE(u.updated_at_ms, k.updated_at_ms) AS rollup_updated_at_ms,
                         CASE COALESCE(NULLIF(BTRIM(r.preferred_pool_strategy), ''), 'balanced')
@@ -517,6 +534,9 @@ impl PostgresControlRepository {
                     page_keys.billable_tokens,
                     page_keys.credit_total,
                     page_keys.credit_missing_events,
+                    page_keys.codex_image_usage_tokens,
+                    page_keys.codex_image_usage_missing_events,
+                    page_keys.codex_image_last_used_at_ms,
 	                    page_keys.last_used_at_ms,
 	                    page_keys.rollup_updated_at_ms,
 	                    COALESCE(summary.candidate_count, 0),
@@ -583,6 +603,9 @@ impl PostgresControlRepository {
                     COALESCE(u.billable_tokens, 0),
                     COALESCE(u.credit_total, '0'),
                     COALESCE(u.credit_missing_events, 0),
+                    COALESCE(u.codex_image_usage_tokens, 0),
+                    COALESCE(u.codex_image_usage_missing_events, 0),
+                    u.codex_image_last_used_at_ms,
                     u.last_used_at_ms,
                     COALESCE(u.updated_at_ms, k.updated_at_ms),
                     r.preferred_pool_strategy AS preferred_pool_strategy,
@@ -727,9 +750,10 @@ impl PostgresControlRepository {
             .execute(
                 "INSERT INTO llm_key_usage_rollups (
                     key_id, input_uncached_tokens, input_cached_tokens, output_tokens,
-                    billable_tokens, credit_total, credit_missing_events, last_used_at_ms,
-                    updated_at_ms
-                 ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+                    billable_tokens, credit_total, credit_missing_events,
+                    codex_image_usage_tokens, codex_image_usage_missing_events,
+                    codex_image_last_used_at_ms, last_used_at_ms, updated_at_ms
+                 ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
                  ON CONFLICT(key_id) DO UPDATE SET
                     input_uncached_tokens = EXCLUDED.input_uncached_tokens,
                     input_cached_tokens = EXCLUDED.input_cached_tokens,
@@ -737,6 +761,10 @@ impl PostgresControlRepository {
                     billable_tokens = EXCLUDED.billable_tokens,
                     credit_total = EXCLUDED.credit_total,
                     credit_missing_events = EXCLUDED.credit_missing_events,
+                    codex_image_usage_tokens = EXCLUDED.codex_image_usage_tokens,
+                    codex_image_usage_missing_events =
+                        EXCLUDED.codex_image_usage_missing_events,
+                    codex_image_last_used_at_ms = EXCLUDED.codex_image_last_used_at_ms,
                     last_used_at_ms = EXCLUDED.last_used_at_ms,
                     updated_at_ms = EXCLUDED.updated_at_ms",
                 &[
@@ -747,6 +775,9 @@ impl PostgresControlRepository {
                     &rollup.billable_tokens,
                     &rollup.credit_total.to_string(),
                     &rollup.credit_missing_events,
+                    &rollup.codex_image_usage_tokens,
+                    &rollup.codex_image_usage_missing_events,
+                    &rollup.codex_image_last_used_at_ms,
                     &rollup.last_used_at_ms,
                     &rollup.updated_at_ms,
                 ],
@@ -877,6 +908,9 @@ impl AdminKeyStore for PostgresControlRepository {
                 COALESCE(u.billable_tokens, 0),
                 COALESCE(u.credit_total, '0'),
                 COALESCE(u.credit_missing_events, 0),
+                COALESCE(u.codex_image_usage_tokens, 0),
+                COALESCE(u.codex_image_usage_missing_events, 0),
+                u.codex_image_last_used_at_ms,
                 u.last_used_at_ms,
                 COALESCE(u.updated_at_ms, k.updated_at_ms),
                 r.preferred_pool_strategy AS preferred_pool_strategy,
@@ -982,6 +1016,9 @@ impl AdminKeyStore for PostgresControlRepository {
             billable_tokens: 0,
             credit_total: 0.0,
             credit_missing_events: 0,
+            codex_image_usage_tokens: 0,
+            codex_image_usage_missing_events: 0,
+            codex_image_last_used_at_ms: None,
             last_used_at_ms: None,
             updated_at_ms: key.created_at_ms,
         };
diff --git a/crates/llm-access-store/src/postgres/usage.rs b/crates/llm-access-store/src/postgres/usage.rs
index e9df0049..25ae1cb6 100644
--- a/crates/llm-access-store/src/postgres/usage.rs
+++ b/crates/llm-access-store/src/postgres/usage.rs
@@ -23,6 +23,78 @@ use super::{
 };
 
 impl PostgresControlRepository {
+    /// Accumulate successful Codex image usage for admin visibility without
+    /// affecting normal billable-token quota rollups.
+    pub async fn record_codex_image_key_usage(
+        &self,
+        key_id: &str,
+        usage_tokens: Option<u64>,
+        used_at_ms: i64,
+    ) -> anyhow::Result<()> {
+        self.ensure_connection_alive()?;
+        let usage_missing_events = if usage_tokens.is_none() { 1_i64 } else { 0_i64 };
+        let usage_tokens = usage_tokens
+            .map(i64::try_from)
+            .transpose()
+            .context("codex image usage tokens exceed i64")?
+            .unwrap_or(0);
+        self.client
+            .execute(
+                "INSERT INTO llm_key_usage_rollups (
+                    key_id,
+                    input_uncached_tokens,
+                    input_cached_tokens,
+                    output_tokens,
+                    billable_tokens,
+                    credit_total,
+                    credit_missing_events,
+                    codex_image_usage_tokens,
+                    codex_image_usage_missing_events,
+                    codex_image_last_used_at_ms,
+                    last_used_at_ms,
+                    updated_at_ms
+                 )
+                 SELECT
+                    k.key_id,
+                    0,
+                    0,
+                    0,
+                    0,
+                    '0',
+                    0,
+                    $2,
+                    $3,
+                    $4,
+                    NULL,
+                    $4
+                 FROM llm_keys k
+                 WHERE k.key_id = $1
+                 ON CONFLICT(key_id) DO UPDATE SET
+                    codex_image_usage_tokens =
+                        llm_key_usage_rollups.codex_image_usage_tokens
+                        + EXCLUDED.codex_image_usage_tokens,
+                    codex_image_usage_missing_events =
+                        llm_key_usage_rollups.codex_image_usage_missing_events
+                        + EXCLUDED.codex_image_usage_missing_events,
+                    codex_image_last_used_at_ms = CASE
+                        WHEN llm_key_usage_rollups.codex_image_last_used_at_ms IS NULL THEN
+                            EXCLUDED.codex_image_last_used_at_ms
+                        ELSE GREATEST(
+                            llm_key_usage_rollups.codex_image_last_used_at_ms,
+                            EXCLUDED.codex_image_last_used_at_ms
+                        )
+                    END,
+                    updated_at_ms = GREATEST(
+                        llm_key_usage_rollups.updated_at_ms,
+                        EXCLUDED.updated_at_ms
+                    )",
+                &[&key_id, &usage_tokens, &usage_missing_events, &used_at_ms],
+            )
+            .await
+            .context("record postgres codex image key usage")?;
+        Ok(())
+    }
+
     /// Resolve the effective proxy attribution for one consumed usage event.
     pub async fn resolve_usage_proxy_attribution(
         &self,
diff --git a/crates/llm-access-store/src/records.rs b/crates/llm-access-store/src/records.rs
index 56f6cd7c..5039f57a 100644
--- a/crates/llm-access-store/src/records.rs
+++ b/crates/llm-access-store/src/records.rs
@@ -107,6 +107,12 @@ pub struct KeyUsageRollup {
     pub credit_total: f64,
     /// Number of events missing credit usage.
     pub credit_missing_events: i64,
+    /// Accumulated Codex image-generation tokens reported by upstream.
+    pub codex_image_usage_tokens: i64,
+    /// Number of successful Codex image responses missing upstream usage.
+    pub codex_image_usage_missing_events: i64,
+    /// Last successful Codex image usage timestamp.
+    pub codex_image_last_used_at_ms: Option<i64>,
     /// Last usage timestamp.
     pub last_used_at_ms: Option<i64>,
     /// Update timestamp in Unix milliseconds.
diff --git a/crates/llm-access/src/admin.rs b/crates/llm-access/src/admin.rs
index 4fe70c7a..98eed31b 100644
--- a/crates/llm-access/src/admin.rs
+++ b/crates/llm-access/src/admin.rs
@@ -7371,6 +7371,9 @@ mod tests {
             usage_output_tokens: 0,
             usage_credit_total: 0.0,
             usage_credit_missing_events: 0,
+            codex_image_usage_tokens: 0,
+            codex_image_usage_missing_events: 0,
+            codex_image_last_used_at: None,
             remaining_billable: 1_000_000,
             last_used_at: None,
             created_at: 10,
diff --git a/deployment-examples/systemd/llm-access-codex-image.service.template b/deployment-examples/systemd/llm-access-codex-image.service.template
index 36ea7ea5..c5bdb1e1 100644
--- a/deployment-examples/systemd/llm-access-codex-image.service.template
+++ b/deployment-examples/systemd/llm-access-codex-image.service.template
@@ -9,8 +9,8 @@ Type=simple
 User=ts_user
 Group=ts_user
 TimeoutStartSec=120
-# Requires llm-access Postgres migration 0030 before start; the binary fails
-# fast if llm_key_route_config.codex_image_generation_enabled is missing.
+# Requires llm-access Postgres migrations 0030 and 0031 before start; the
+# binary fails fast if Codex image route/usage rollup columns are missing.
 EnvironmentFile=/etc/llm-access/llm-access.env
 Environment=STATICFLOW_LOG_DIR=/var/log/staticflow-runtime
 Environment=STATICFLOW_LOG_SERVICE=llm-access-codex-image
diff --git a/scripts/release_llm_access_cloud_codex_image_only.sh b/scripts/release_llm_access_cloud_codex_image_only.sh
index 9cc95e23..c4462712 100755
--- a/scripts/release_llm_access_cloud_codex_image_only.sh
+++ b/scripts/release_llm_access_cloud_codex_image_only.sh
@@ -63,8 +63,9 @@ fi
 GCP_SSH_KEY="$(expand_path "$GCP_SSH_KEY")"
 SSH_OPTS=(-i "$GCP_SSH_KEY" -o IdentitiesOnly=yes -o BatchMode=yes)
 
-# The image gateway is read-only against Postgres. Apply llm-access migration
-# 0030 from the control-plane service before activating this binary.
+# The image gateway does not run Postgres migrations itself. Apply llm-access
+# migrations 0030 and 0031 before activating this binary; its DSN needs read
+# access plus narrow writes to the Codex image key usage rollup columns.
 LLM_ACCESS_ACTIVATE_TARGET=image "$ROOT_DIR/scripts/prepare_llm_access_cloud_release.sh"
 "$ROOT_DIR/scripts/render_llm_access_cloud_bundle.sh" "$RENDER_DIR"