---
title: "Configure Codex"
description: "Choose account identity, model source, and model capabilities independently."
version: "en"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ochub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Codex

## Account and model source

Choose **Official**, **Model provider**, or **Manual configuration** as the model source, and select **ChatGPT** or **No account** independently. Sign in through Codex; choosing ChatGPT in OcHub does not sign in or verify a subscription.

1. Add the third-party URL, API key, protocol, and models under **Model providers**.
2. Add a Codex connection, choose that provider, and select ChatGPT to retain an existing real login.
3. Choose a model and leave context management on **Auto**.
4. Review the configuration, save and switch the connection, then start a new Codex session.

A provider connection keeps upstream credentials in the supplier. Manual connections use the address and API key entered in the connection. Keeping ChatGPT login alongside an independent API key does not qualify for experimental context management.

**Save** stores a Codex draft without rewriting the live connection files. **Save and activate** saves the draft and switches to it. If the currently active connection changed on disk, OcHub first shows the same version diff and asks whether to save or revert those live edits. **Check configuration** checks local configuration requirements only; it sends no inference request and does not verify subscriptions or backend capabilities. Remote workspaces require an updated node supporting draft operations.

Virtual login is under **Advanced** for compatibility with clients without a real account. It grants no subscription or official quota and cannot replace real credentials.

## Context management

| Choice | Behavior |
| --- | --- |
| Auto | Uses the experimental Codex entry point for the default official endpoint; does not automatically enable it for third-party or OcHub routes |
| On | For ChatGPT + OcHub, explicitly enables Token Budget and History / Notes; requires a compatible distribution server |
| Off | Keeps the experiment disabled during subsequent endpoint injection |

**Pending Codex verification** is a configuration state, not proof of backend availability. Independent API-key connections do not enable this account extension.

For a distribution server implementing History / Notes, select ChatGPT, bind a supplier with exactly one Responses channel, and choose **On**. OcHub preserves real login credentials and explicitly writes `[features.token_budget] enabled = true` and `use_history_notes_extension = true`. This uses Codex's explicit configuration path without editing ID-token plan claims. Codex must include the extension and a known model context window; managed feature restrictions still apply. Remote control continues using the official `chatgpt_base_url`, which OcHub does not redirect. Provider capabilities and official pairing still require live verification.

Keep the same distribution API key for a history session; start a new session after changing keys.

### Automatic activation requirements

The corresponding Codex source checks all of these in `apply_experimental_context`:

- `[features.context_management] experimental_mode = true`.
- Exact provider name `OpenAI`.
- No base URL, or a URL ending in `/backend-api/codex` after removing trailing slashes.
- `requires_openai_auth = true`.
- No `env_key`, `experimental_bearer_token`, `auth`, or `aws` provider fields; empty strings still count as present.
- `Chatgpt` authentication with a Plus, Pro, or ProLite plan.
- Token Budget can be enabled and is not pinned off by managed requirements.

Passing this check enables Token Budget and `use_history_notes_extension`. Actual use also requires a known model context window, an installed History / Notes extension, and working history ingestion, retrieval, and notes services. Explicit Token Budget configuration and model defaults are separate activation paths.

### History and compaction are separate

OcHub forwards the ten History / Notes operations, including `thread_hint`, under its scoped `/backend-api/codex/alpha/` route to the supplier's Responses endpoint sibling `alpha/` path. Requests need no model field. Opaque argument bytes, encrypted results, and upstream statuses are preserved; real OAuth and account headers are replaced with supplier authentication. Mixed or multiple enabled channels are rejected for these operations, and writes are never retried on another channel.

The distribution server must implement history ingestion, storage, retrieval, notes, user ownership checks, and persistent session-to-account affinity. OcHub does not supply that backend or verify it when saving. Keep the supplier unchanged for existing sessions. **Auto** remains conservative for gateways. The older 0.5.16 claim of complete history support from compaction alone was incorrect.

`/responses/compact` only provides remote compaction. OcHub forwards `/v1/responses/compact` and the Codex backend equivalent to Responses upstreams that support it. Chat or Messages conversion cannot substitute for this capability.

## Model capability declarations

Under **Model providers → Edit → Models**, open **Model capabilities** for a selected model.

| Field | Meaning |
| --- | --- |
| Responses Lite: Auto | Undeclared and conservatively disabled; never inferred from an official model with the same name |
| Responses Lite: Supported / Unsupported | Explicit `use_responses_lite` declaration in the generated Codex catalog |
| Remote compaction: Auto | Unverified; actual Responses requests determine availability |
| Remote compaction: Supported | User declaration, still requiring a real request to verify |
| Remote compaction: Unsupported | Gateway rejects this model's remote compaction requests |
| Context window | Positive integer; blank uses catalog defaults |

These settings are marked **User declared · Unverified**. Fetching a model list does not verify Lite, compaction, or history services. Declarations are scoped to the supplier and upstream model; aliases use the mapped upstream model's declarations.

Lite changes Responses request behavior. It is neither an authentication mode nor a context-management prerequisite. Lite requests require native Responses channels and cannot fall back to Chat / Messages conversion.

## Route isolation

New real-login connections use an address such as:

```text
http://127.0.0.1:4180/connection/rd-…/backend-api/codex
```

The URL's local gateway credential identifies the supplier independently of rotating account tokens. Account credentials remain in `auth.json`; OcHub uses the supplier API key upstream and removes the local routing credential. Different suppliers no longer share a single OAuth route binding.

The URL contains a local credential and should not be shared publicly. The listener remains loopback-only. Route authentication does not verify a ChatGPT subscription. Disabling its key rejects the connection.

Legacy URLs without `/connection/…` still support the manually configured global OAuth binding. Save and activate the connection again to migrate.

## Local history, MCP, and skills

Local history unification and migration manage session files, not the experimental History / Notes backend. Exit Codex and retain backups before changing history locations. Enable Codex in the MCP or Skills page, sync, and restart sessions after configuration-directory changes.

See [Codex advanced configuration](/codex/advanced) and [Model providers](/getting-started/relay).

Source: https://docs.ochub.org/codex/configure/index.mdx