Host setup automation · verified 2026-10-10

Enable native Codex images through codex-lb

For a subscription-backed codex-lb provider that skips local OpenAI login, add the static actor-authorization marker. Codex uses it to decide whether to expose its native image tool.

This handoff targets an agent updating host-provisioning tooling. The behavior was checked against Codex CLI 0.162.1 and confirmed by native generation and editing in a fresh session using gpt-6.1-sol. Apply this to the login-skipping codex-lb configuration described here; other providers and authentication modes need their own eligibility check.

The change

Edit the active machine-local Codex config, normally ~/.codex/config.toml (or the config under the effective CODEX_HOME). Add this header to the existing provider table:

[model_providers.codex-lb]
name = "openai"
wire_api = "responses"
requires_openai_auth = false
http_headers = { "x-openai-actor-authorization" = "codex-lb" }

This is a fragment, not a replacement provider definition. The only setting added during the fix was http_headers. The existing provider selection, lowercase name, base URL, model, transport settings, credentials, and requires_openai_auth = false were preserved. If headers already exist, merge this entry rather than replacing the map.

Why text worked but images were unavailable

The host was already using codex-lb backed by a subscription. Text inference worked. However, the provider deliberately skipped local OpenAI login and had no actor marker, so Codex's client-side eligibility checks withheld the native image tool before any image request could reach the proxy. Having the imagegen skill installed did not change the callable tool inventory.

There are two separate provider checks in 0.162.1. Passing the extension-registration check alone is insufficient:

CheckProvider conditionWhy the marker matters
Image extension registrationis_openai(), or requires_openai_auth, or uses_openai_actor_authorization()The marker activates the actor-authorized branch while preserving the existing provider name and auth mode.
Image tool planningActor-authorized provider, or requires_openai_auth = true with current Codex-backend authenticationThe marker also passes the second check. A provider name change alone does not.

uses_openai_actor_authorization() specifically requires both requires_openai_auth = false and a static http_headers entry whose name equals x-openai-actor-authorization case-insensitively and whose value is nonempty after trimming. An environment-header entry is not what this predicate inspects.

The image-tool planner also checks that image generation is enabled, the provider advertises image-generation capability, the model accepts image input, and cached local authentication does not report a Free plan. The header fixes the missing provider eligibility signal; it does not override the remaining checks.

Changing name = "openai" to "OpenAI" was considered because is_openai() uses an exact comparison with "OpenAI". That would address only the first gate. It would leave the second unsatisfied in this auth mode, and codex-lb documents the lowercase name for other client behavior. Preserve name = "openai".

What “actor authorization” means here

In codex-lb's documented setup, the literal value "codex-lb" is a non-secret client capability marker. It tells Codex to treat this provider as using the actor-authorized path for tool eligibility. It is not a password, subscription token, API key, or a grant of account entitlement, and it does not authenticate requests to codex-lb.

If the proxy requires an API key, preserve its independent credential configuration, such as env_key = "CODEX_LB_API_KEY". Do not replace that credential with the marker. Conversely, this successful probe required no new direct OpenAI API key and no API-key fallback: the existing subscription-backed proxy setup handled the native image requests.

The alternative supported path is requires_openai_auth = true with a current local Codex-backed login. Do not convert that setup to the marker path automatically. Adding the marker while keeping requires_openai_auth = true does not activate the actor predicate.

What the provisioning agent should implement

  1. Resolve the effective configuration. Honor the configured Codex home and the provider selected for the intended session. Update the machine-local provider definition rather than assuming the current working directory is a project with a suitable config.
  2. Limit the change to the supported deployment mode. For an intentionally login-skipping codex-lb provider, retain requires_openai_auth = false and ensure the static marker exists. Leave the local-login path intact when that is the chosen setup.
  3. Make the edit idempotent. Use a TOML-aware update, back up the original, and merge the header without duplicate keys or provider tables. Handle header-name casing deliberately because Codex compares it case-insensitively. If a different nonempty actor value already exists, report that configuration for deliberate handling rather than silently replacing it.
  4. Preserve unrelated settings. Keep the provider name, base URL, model, proxy credentials, other headers, and transport options. Validate the resulting TOML and confirm that only the intended header changed semantically. Do not print credential-bearing config or auth files.
  5. Keep the Codex base URL. Native image calls append images/generations and images/edits to the active provider base. For the documented codex-lb setup, retain its /backend-api/codex base and verify the proxy supports those routes. Do not switch the provider to /v1 as part of this fix.
  6. Require a fresh-session probe. Existing sessions retain initialized provider/tool state. Changing the file does not establish that an already-running agent has acquired the tool.

Acceptance check: configuration plus actual images

Record the active CLI version, model, and provider. These checks are useful prerequisites, but they do not prove the native tool is exposed or that image requests work:

codex --version
codex features list | rg 'image_generation|imagegenext'

The verified output was codex-cli 0.162.1 and image_generation stable true. No imagegenext entry appeared; its absence was not a failure.

Start a new session and give its agent this probe:

Verify the effective model, provider, config location, and Codex CLI version without exposing credentials. Do not change configuration or authentication.

Check whether native image generation is actually callable. In the verified session its tool name was image_gen.imagegen, callable as tools.image_gen__imagegen; discover the current tool rather than assuming that spelling is permanent.

Use the native tool to generate one solid red circle centered on a plain white square background, with no text or effects. Save its output to /tmp/codex-imagegen-probe.png. Inspect that file, then use the same native tool to edit only the circle's fill to blue. Save the edit to /tmp/codex-imagegen-edit-probe.png.

Do not substitute SVG, canvas, scripted drawing, or a direct API-key call. Verify that both output files are valid PNGs, record their dimensions, and inspect their contents. If the tool is absent or a request fails, record the exact non-secret failure instead of claiming success.

Write the session details, exact tool name, generation/edit outcomes, and any failures to /tmp/response.md. Do not dump auth files or secrets.

Observed result: the fresh session exposed the native tool, generated the red circle, and edited it to blue. Both saved outputs were valid 1254 × 1254 PNGs, and each copy matched its native output byte-for-byte. Visual inspection confirmed the requested colors and composition. The older session still lacked the tool after the file edit.

This establishes successful native generation and editing through the configured provider. It does not independently trace the proxy's internal upstream routing, promise pixel-identical preservation during edits, or guarantee identical eligibility behavior in future Codex versions.

Responses transport and image requests are separate

wire_api = "responses" selects the inference transport; it does not by itself enable Codex's image tool. The standalone native image implementation used here makes separate image-generation and image-edit requests. The Responses API's hosted image_generation tool is another integration surface, not the mechanism this config change enabled.

Sources for the tooling change

The public codex-lb compatibility note documents this exact marker contract. The version-pinned Codex sources explain why it is needed; use the shipped client version when checking whether these conditions still apply.