Codex Huge Context Setup

Codex Huge Context

Use this skill when configuring, repairing, or auditing Codex's one-million-token context setup. The intended topology is a direct API inference route that preserves the normal ChatGPT login for Gmail, Calendar, and other connector OAuth:

Codex inference -> Keychain auth helper -> https://api.openai.com/v1/responses
Codex connectors -> normal ChatGPT login in auth.json

This is not an HTTP proxy. The API remains authoritative for access, actual model limits, and billing.

Atomic provider and context invariant

Treat the provider selector, context window, compaction threshold, and custom model catalogue as one atomic configuration. In Peter's normal ChatGPT-authenticated setup, model_provider = "openai" selects the ChatGPT-backed route; never attach this skill's direct-API 922000 context window and 700000 compaction threshold to that route. The provider identifier alone does not determine transport: built-in openai with API-key authentication can also use the API. This skill and its preflight require the named openai_api_direct provider below so inference uses its dedicated Keychain helper while connector login stays separate.

That split configuration can leave a 700,000-token compaction threshold attached to a smaller provider or model-metadata limit. Codex may also clamp the requested window, so root numbers alone do not prove the usable context. A browser- or Computer Use-heavy thread can grow past the provider's real limit before compaction, receive context_length_exceeded, and become unable to compact because the compaction request itself no longer fits. Verify the fresh session's reported effective window as well as the files on disk.

The required preflight treats this mismatch as fatal. Do not launch or resume Codex after any config writer, app settings change, model change, or fleet sync until the preflight passes. If it reports an unsafe split configuration, restore model_provider = "openai_api_direct", restart every Codex desktop/shared app server, and start or fork a fresh thread. Resuming the failed thread preserves its recorded provider.

Safe input window

GPT-6 Astra exposes a 1,050,000-token total context window and can produce up to 128,000 output tokens. Codex does not set a smaller output budget on normal Responses API turns, so the catalogue must describe the safe input allowance rather than the raw total:

1,050,000 total - 128,000 maximum output = 922,000 safe input

Use the same safe input policy for all four direct-provider catalogue models:

• gpt-5.6-sol
• gpt-5.6-terra
• gpt-5.6-luna
• gpt-6-astra

Preserve the operator's selected supported model when configuring context. The examples below use Astra; enabling large context does not authorize replacing another selected model.

Codex applies its normal 95% effective-window reserve to the 922,000-token input allowance, so it reports and guards about 875,900 usable tokens. Set automatic compaction to 700,000 total active tokens. That leaves about 175,900 tokens inside Codex's effective guard and 222,000 tokens before the provider's safe input ceiling for the next prompt, tool schemas and results, instructions, serialization overhead, and compaction itself. This larger margin is intentional: Codex 0.144.6 checks already-recorded context before adding the next user message and context updates, and a terminal response that crosses the threshold may not compact until the following turn. The observed large-context workload grew by about 144,000 tokens in one turn, which made the former 820,000 threshold too aggressive.

Long-context requests above 272,000 input tokens use the provider's higher long-context pricing. Do not enable this route accidentally for workloads that do not benefit from it.

Required files

~/.codex/models-api-1m.json must contain these values for all four model slugs while preserving the rest of each model entry:

{
  "context_window": 922000,
  "max_context_window": 922000,
  "auto_compact_token_limit": 700000
}

Leave effective_context_window_percent absent to use Codex's 95% default, or set it explicitly to the integer 95. Null, floating-point, or other values are invalid.

Start from the complete native catalogue for the installed Codex release, including its reviewer models: a custom catalogue replaces the built-in catalogue rather than overlaying selected entries. Use every model's genuine metadata and a client satisfying its minimum version. Preserve instructions, tool capabilities, and every safety field, including required review behavior; override only the context and compaction fields above. Never invent Astra metadata or relabel a Sol entry as Astra. The API context contract above supports the direct-provider override; it does not expand ChatGPT entitlement or relax client safety requirements. The preflight validates context and credential delivery, not the provenance of the remaining catalogue metadata.

The root section of ~/.codex/config.toml needs:

model = "gpt-6-astra"
model_provider = "openai_api_direct"
model_context_window = 922000
model_auto_compact_token_limit = 700000
model_auto_compact_token_limit_scope = "total"
model_catalog_json = "/Users/steipete/.codex/models-api-1m.json"

[model_providers.openai_api_direct]
name = "OpenAI API direct"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
requires_openai_auth = false

[model_providers.openai_api_direct.auth]
command = "/Users/steipete/.codex/bin/fetch-openai-inference-key.zsh"
timeout_ms = 5000
refresh_interval_ms = 300000

Replace legacy values such as model_context_window = 1050000 or model_auto_compact_token_limit = 233000; do not leave duplicate root keys. Keep the scope at total, because the safety budget applies to the complete active request, not only content added after a compaction prefix.

Before modifying a host, back up both config files to date-stamped sibling files. Do not replace unrelated project, plugin, MCP, notification, approval, model-selection, or reasoning settings.

API credential delivery

The auth command reads a dedicated Keychain delivery copy, never a value in TOML or an environment variable:

#!/bin/zsh
set -euo pipefail
exec /usr/bin/security find-generic-password \
  -a Codex \
  -s "Codex OpenAI inference API" \
  -w /Users/steipete/Library/Keychains/login.keychain-db

Resolve and verify the host's actual Keychain path at installation time; the example is host-specific. Keep that absolute, non-secret path inside the external executable, not $HOME/~, a provider override, or non-empty auth.args. Managed autoreview replaces the client's HOME/USERPROFILE and XDG config/data/state/cache directories. Implicit Keychain selection can then return exit 44 (SecKeychainSearchCopyNext item not found) even though parent-session delivery succeeds. Repair the wrapper's Keychain selection—not the reviewer's HOME, filesystem grants, or credential access. Inspect an existing helper before changing it; it may already use explicit selection.

Use $one-password before handling the API key. The canonical value is the OPENAI_API_KEY field in Molty's AI API Key - OpenAI - OPENAI_API_KEY - Serviceable Access item. Read it through the service-account workflow inside the shared op-work tmux session and store/update only the Keychain copy. Never print, copy over SSH, place in a profile, or write it to a temporary file.

The Keychain item should allow /usr/bin/security. A Keychain read normally produces no prompt. A login Keychain locked after reboot, or a command launched via noninteractive SSH, can fail with error 36 (User interaction is not allowed). Do not work around that failure with a plaintext file or a long-lived secret daemon: unlock the host from its local graphical session, install the item there, then use Codex from that local session.

Before the first fresh or resumed Codex launch on a configured machine, run the secret-safe preflight. It validates the direct-provider config, safe input and compaction values, all four catalogue entries, helper executable, and non-empty helper delivery without printing the credential or helper stderr:

ruby ~/.codex/skills/agent-scripts/codex-huge-context/scripts/preflight.rb

Do not mark a rollout complete or launch Codex when this fails. With requires_openai_auth = false, a missing Keychain delivery copy cannot fall back to the normal Codex login: the direct provider can reach api.openai.com/v1/responses without a bearer header and surface an opaque HTTP 401 instead. The preflight fails earlier with the bootstrap action needed. An unset GITHUB_PAT_TOKEN warning is independent and non-blocking for inference; it explains a concurrent GitHub MCP startup failure but must not be confused with OpenAI API authentication.

The preflight's provider check is not cosmetic. A machine with the direct provider table and million-token catalogue present but root model_provider = "openai" is broken, even when every numeric value is otherwise correct.