Skip to main content

Configure Codex manually (ChatGPT app)

Orbit AI API Team2026/07/113 min read

This is the manual alternative for configuring Codex. We recommend the graphical AI Toolbox guide for Codex for managing providers, models, and keys.

1. Confirm Codex is installed​

Complete the environment check, then run:

codex --version

Continue after the command returns a version number. The first launch of codex creates its user-level configuration directory.

2. Open the Codex configuration directory​

  1. Press Win + R, enter this path, and press Enter:
%USERPROFILE%\.codex
Screenshot: Windows Run dialog and Codex configuration directoryShow Win + R, the directory path, and the contents of the .codex folder.

Linux users use the same ~/.codex directory.

3. Understand the main files​

The directory may contain these files. This guide uses the first two; the rest can be ignored for now:

  • config.toml: Codex's main user-level configuration file for relay services, model providers, MCP, and other settings.
  • auth.json: Stores the API key from the Orbit AI API Console.
  • AGENTS.md: Defines global instructions for Codex. It can remain empty when not needed.

:::danger Important

If the initial installation did not create them, create these three files manually. Configure config.toml and auth.json in the next steps.

:::

4. Configure config.toml​

Replace MODEL_NAME with the full name from the Model Gallery, then add this content to your user-level config.toml:

model = "MODEL_NAME"
model_provider = "orbitai"
model_reasoning_effort = "high"
model_verbosity = "high"
disable_response_storage = true

[model_providers.orbitai]
name = "Orbit AI API"
base_url = "https://orbitaiapi.site/v1"
wire_api = "responses"
requires_openai_auth = true

Custom providers must be defined in the user-level ~/.codex/config.toml, not a project's .codex/config.toml. Adjust model_reasoning_effort and model_verbosity to the model's capabilities.

5. Configure the API key​

Review Create an API key, create a key for Codex in the console, and add this content to auth.json:

{
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

Replace YOUR_API_KEY with the actual value and save. Never commit the key to a repository or include it in screenshots or frontend applications.

6. Test a conversation​

Run this command in a Windows, macOS, or Linux terminal:

codex

If the interactive interface responds normally, configuration is complete. For authentication or model errors, check config.toml, auth.json, the Base URL, model name, token status, and the model's Responses API compatibility.