Codex harness configuration

The Codex harness configuration map and the turn-level behavior each setting controls. Part of the Codex harness guide; Where each section moved lists every section.

Configuration

Prefer auth.order.openai for subscription-first/API-key-backup ordering. Existing legacy Codex auth profile ids and legacy Codex auth order are doctor-only legacy state; do not write new legacy Codex GPT refs.

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

For a Codex-compatible effective route, both profiles above remain candidates for the same Codex run. Profile order chooses credentials, not the runtime. Changing auth order does not make a custom, Completions, HTTP, or request-overridden route Codex-compatible. Valid model-scoped Fast-mode and cutoff controls are runtime controls, not request overrides.

Restricted turns and ring zero

OpenClaw evaluates Codex tool policy on every turn. Compatible conversation-wide restrictions reuse the same native thread, including after a connection restart. Temporary restrictions, such as per-run allowlists, scheduled restrictions, or sender-specific restrictions, use an isolated thread where necessary and preserve the conversation's existing binding. A temporary first turn does not establish a permanent restricted binding.

When a managed restricted thread's creation policy changes, or an older binding has no saved policy fingerprint, OpenClaw creates a compatible successor and projects the prepared conversation history into it. A failed replacement keeps the previous binding. Existing ownership guards still reject replacing an externally owned thread or one protected by active work; changing policy does not broaden that thread's permissions.

An ordinary policy-restricted turn occurs when an explicit OpenClaw tool policy cannot be mapped safely onto Codex's native tool surface. Common triggers include:

• a finite tools.allow list or an internal per-run allowlist
• disableTools or a sender/group policy that denies all tools
• a tools.deny entry with a wildcard, tool group, unknown name, or name that is not in the Codex harness's audited safe-deny set
• an applicable agent, provider, group, sender, sandbox, subagent, inherited, scheduled, or runtime tool policy with one of those restrictions

Default tool-profile narrowing alone does not trigger this mode. A deny list containing only audited OpenClaw-owned tools can also stay on the normal native surface; the harness enforces those denies without disabling unrelated Codex capabilities. See Native tool-policy enforcement for the generic harness contract and Codex harness reference for the current Codex rules.

For an ordinary policy-restricted turn, OpenClaw disables Codex native Code Mode, removes environment selections, disables and verifies inherited and native configured MCP servers, and disables native hook relays. Static configured MCP tools that pass the effective policy move to OpenClaw's dynamic surface for that turn. Other OpenClaw dynamic tools use the same policy. The bounded workspace AGENTS.md snapshot still reaches the model as thread-level developer instructions because project instructions are context, not tool authority.

Ring zero is stronger and separate. It is the host-owned OpenClaw system agent used for setup and repair operations. The host activates it with the single openclaw tool; normal agent config cannot opt a chat into ring zero. Ring-zero turns keep only that host-scoped tool, replace ambient Codex instructions with host-authored setup instructions, disable native tools and MCP servers, and suppress workspace project documents, including the AGENTS.md developer-instruction carrier.

Other narrow internal modes also suppress project documents: lightweight bootstrap turns, message-only source replies, and tool-disabled internal turns. They share some isolation settings with policy-restricted turns but are not synonyms for ring zero.

Project instructions

Codex loads AGENTS.md files through native project-document discovery. For normal app-server threads, OpenClaw raises Codex's aggregate root-to-working- directory budget from the upstream 32 KiB default to a bounded 128 KiB so later scoped instructions are not silently clipped. Ordinary conversation tool-policy restrictions preserve that budget because project instructions are context, not tool authority. Their isolated native environment cannot read workspace files, so OpenClaw supplies the bounded workspace AGENTS.md snapshot as thread-level developer instructions. An explicitly authored native project_doc_max_bytes setting overrides the 128 KiB fallback for ordinary threads; Codex's materialized 32 KiB default does not. Lightweight, ring-zero, message-only, and tool-disabled internal turns set the native project-document budget to zero instead.

An inherited agent-workspace AGENTS.md snapshot stays fixed for its native thread, including when the file is edited, emptied, or removed. Start a new session to load the current workspace instructions.

This byte budget is separate from the character-based workspace bootstrap limits configured through agents.defaults.bootstrapMaxChars and agents.defaults.bootstrapTotalMaxChars.

/context reports native project documents as unverified because app-server exposes their source paths but not the retained byte counts needed to tell whether any individual file was fully loaded or truncated.

Compaction

agents.defaults.compaction.model selects the model for OpenClaw host summaries, including the history summary before seeding a fresh Codex thread. Doctor preserves this setting. Native Codex compaction and /compact remain owned by Codex and do not use this override. A locked model selection also takes precedence over the host summary model.

Do not set compaction.provider on Codex-backed agents. Doctor removes unsupported provider overrides and migrates legacy Lossless configuration as described below.

An authored models.providers.*.models[].contextTokens cap is forwarded to Codex thread start and resume as model_context_window. Codex clamps the value to the model's native maximum and derives automatic compaction from the capped window. This applies to configured model chats even when Codex supplies the model catalog. When the model entry has no authored cap, OpenClaw sends no override. Sessions pinned to an existing native runtime retain their own context settings instead of inheriting the outer agent's model cap.

On ordinary configured model chats, that authored cap also bounds host context engine assembly and maintenance. OpenClaw reserves space for the current input, instructions, tools, and output before assembling history, and retains the successful assembly's budget when recovering accepted turns. A smaller current run budget still wins. This is operator policy, not discovery of Codex's usable allowance: Codex can apply a smaller native limit or a model-specific reserve. Choose the authored limit with enough native headroom. Unconfigured models do not inherit another model's cap.

Lossless remains supported as a context engine for assembly, ingestion, and maintenance around Codex turns, configured through plugins.slots.contextEngine: "lossless-claw" and plugins.entries.lossless-claw.config.summaryModel, not through agents.defaults.compaction.provider. openclaw doctor --fix migrates the old compaction.provider: "lossless-claw" shape to the Lossless context-engine slot when Codex is the active runtime, but native Codex still owns compaction. The native app-server harness supports context engines that need pre-prompt assembly; generic CLI backends, including codex-cli, do not provide that host capability.

When OpenClaw has no resolved token budget, context engines receive the usable window reported by Codex. Assembly can reuse a bound thread's observation only for the same model and when no newer unreported turn superseded it. Before an observation is available, only an explicit authored cap supplies a budget; otherwise the budget remains unknown. Resolved OpenClaw budgets take precedence, and learning a native window does not change the thread's bootstrap policy.

For explicitly budgeted context-engine projections, history selected by assembly is not silently shortened again to fit a single native user input. It travels as quoted-user fragments of at most 8 KiB of UTF-8 text, with images carried separately, preserving text, sender labels, and image order. Framing overhead is reserved before assembly. The current request remains normal user input, separate from quoted history.

OpenClaw seeds selected history once when a native thread starts. Later selections that extend the same history append only their new suffix; an unchanged selection is not injected again, including after a restart or native thread resume. A rewritten selection or changed bootstrap epoch starts a fresh native thread with the new selected history instead of reinjecting the full selection into the old thread. Codex owns the resulting native history and compaction and may summarize it. Use the built-in OpenClaw runtime (agentRuntime.id: "openclaw") when a context engine must fully control the model's history and compaction.

Selected saved attachments are restored under the same finite remaining history allowance used for assembly. Complete restored text, file wrappers, sender labels, separators, and image estimates consume that allowance together. An expansion that exceeds it stops before native history or inference is dispatched, instead of silently clipping the selected quote. Existing file-extraction limits and visible extraction dispositions remain the host media owner's policy.

Ordinary assembly failures retain the existing prompt fallback. Saved attachment failures, continuations, and runtime refreshes retain their stricter handling. A failed fresh-thread seed is not marked ready. An uncertain append to a reused thread releases its OpenClaw binding without deleting the native transcript, so a retry starts fresh instead of blindly repeating the append. A crash after an append but before its acknowledgment is saved can still require a fresh thread; this carrier does not introduce an exactly-once durability guarantee. Transport limits still apply and produce an error instead of a partial history.

Fresh Codex threads, including ordinary Fork conversation sessions, receive recent saved history within a bounded continuity window. Conversation text and summaries that fit this window are preserved without a separate per-message cutoff; longer history keeps its newest tail. Tool payloads and restored attachments retain their own limits.

For Codex-backed agents, /compact starts native Codex app-server compaction on the bound thread and waits for its terminal result. The shared agents.defaults.compaction.timeoutSeconds budget applies; on timeout, OpenClaw asks Codex to interrupt the native turn and keeps the per-thread fence until termination is confirmed. It never falls back to a context engine or public OpenAI summarizer. If the native Codex thread binding is missing or stale, the command stops with an error instead of silently switching compaction backends. A SIWC-backed native thread cannot use manual /compact. Automatic in-turn compaction remains available; continue the conversation or start a new session when you need a fresh context.

Cancellation prevents native requests that have not been submitted, including overload retries. After submission, OpenClaw keeps the thread occupied until native completion, interruption, or safe retirement is confirmed. Stopped turns close visible compaction progress without marking unfinished compaction successful or making previously observed native work eligible for replay.

Direct API long context

Codex subscription and direct OpenAI API traffic are separate contracts. The live ChatGPT/Codex catalog commonly exposes a 272000 token model window, while OpenAI documents a 1050000 token Platform API window and 128000 maximum output for GPT-5.5 and GPT-5.6. Both runtime translations use the same safe arithmetic:

1050000 total - 128000 maximum output = 922000 safe active inputautomatic compaction threshold = 700000 active tokens

The native Codex translation is not a Responses parameter set. Codex owns the native thread's context and compaction, so do not add responsesServerCompaction or responsesCompactThreshold to a Codex-backed model.

Start from a complete Codex model catalog compatible with the installed Codex version. For the exact gpt-5.6-sol entry, preserve the rest of the descriptor and set:

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

Codex applies its normal 95% effective-window reserve to the 922000 catalog value, so it reports exactly 875900 usable tokens. Compacting at 700000 leaves 175900 tokens before that effective guard and 222000 before the provider-safe input allowance. This larger margin is deliberate: Codex checks already-recorded context before adding the next user message and context updates, so the threshold must cover one large incoming turn as well as tools, instructions, serialization, and the compaction turn itself.

For standalone Codex CLI or Desktop use, a command-auth custom provider can read the API key from a system keychain or secret manager while the normal ChatGPT login remains available for connectors:

model = "gpt-5.6-sol"model_provider = "openai_api_direct"model_context_window = 922000model_auto_compact_token_limit = 700000model_auto_compact_token_limit_scope = "total"model_catalog_json = "/absolute/path/to/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 = "/absolute/path/to/read-openai-inference-key"timeout_ms = 5000refresh_interval_ms = 300000

The auth helper must print only the key to stdout. Do not put it in TOML.

For the OpenClaw Codex app-server harness, keep the default agent-scoped Codex home and let OpenClaw inject an openai API-key profile. Create the profile by the normal OpenAI API-key auth flow, put its actual id first in auth.order.openai, and pass the catalog and context limits as native Codex app-server arguments:

{  auth: {    order: {      openai: ["openai:api-key"],    },  },  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            args: [              "app-server",              "--listen",              "stdio://",              "-c",              'model_catalog_json="/absolute/path/to/models-api-1m.json"',              "-c",              "model_context_window=922000",              "-c",              "model_auto_compact_token_limit=700000",              "-c",              "model_auto_compact_token_limit_scope=total",            ],          },        },      },    },  },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },      models: {        "openai/gpt-5.6-sol": {          agentRuntime: { id: "codex" },          params: { fastMode: true },        },      },    },  },}

Replace openai:api-key with the actual API-key profile id. The agent-scoped app-server receives only that prepared key; the operator's native ~/.codex ChatGPT login, plugins, connectors, and thread store remain untouched. Use the injected agent-scoped API-key path above for this route rather than relying on homeScope: "user" to provide the intended credential.

The model catalog, model_context_window, total-scope automatic compaction limit, exact openai/gpt-5.6-sol route, and API-key profile order form one configuration unit. Apply them together. OpenClaw can keep embedded and native long-context choices at the same time only when their model refs or agent configurations are distinguishable; one model entry cannot carry both runtime-owned compaction strategies.

After changing the catalog or app-server arguments, restart the Gateway and native Codex app-server, then start a fresh chat. Run /model default -s when an existing session has a model or runtime override. Existing native threads preserve their recorded provider and model settings. Verify the runtime with /status and /codex status, then send a harmless direct API turn before starting a long session.

A process-owned isolated Gateway and app-server run verified this exact openai/gpt-5.6-sol API-key configuration. Codex reported an effective window of 875900. Active context grew from 197032 to 377386, 561957, and 750745 tokens without manual compaction; the next small turn triggered automatic compaction to 75980 active tokens, with a minimum after-compaction snapshot of 68375. Compaction took 2810 ms and persisted a count of one. A durable marker survived compaction and restart, a fixed long response produced 5442 output tokens, and OpenClaw sent the Codex app-server tier priority on every call. That request evidence does not prove which upstream tier processed each call. The full suite took 401.37 seconds. These timings are observations, not service-level guarantees.

The rest of this guide covers deployment shape and routing that requires Codex, guardian approval policy, and native Codex plugins and Computer Use. For full option lists, defaults, enums, discovery, environment isolation, timeouts, and app-server transport fields, see Codex harness reference.