Codex CLI

OpenAI Codex CLI Setup Guide — Quickly connect via the OmwAI relay service with config.toml and auth.json configuration.

Project Overview

Codex CLI is a terminal-based AI coding assistant by OpenAI that runs coding agents locally on your machine. It can generate code, edit files, and execute commands through natural language instructions.

Official repository: https://github.com/openai/codex

Prerequisites

Before you begin, make sure you have:

Node.js installed (v18+ recommended)
Codex CLI installed globally:

npm install -g @openai/codex

Created a Codex-dedicated API token in the OmwAI dashboard (it's recommended to select the codex token group for easier management and rate limiting)
Your OmwAI site address ready (e.g. https://api.example.com)

Configuration Directory

Codex CLI stores its configuration files in the .codex folder under your user home directory:

System	Path
Windows	`%userprofile%\.codex\`
macOS	`~/.codex/`
Linux	`~/.codex/`

There are three main files in this directory:

File	Purpose
`config.toml`	Core config — relay address, model, etc.
`auth.json`	Stores your API Key
`AGENTS.md`	Global prompt instructions for Codex (optional)

If these files don't exist, create them manually.

Configure config.toml

Create or edit config.toml with the following content:

disable_response_storage = true
model = "gpt-5.2"
model_provider = "omwai"
model_reasoning_effort = "xhigh"
model_verbosity = "high"

[features]
web_search_request = true

[model_providers.omwai]
base_url = "https://your-site-address/v1"
name = "omwai"
requires_openai_auth = true
wire_api = "responses"

Configuration reference:

Field	Description
`model`	Model name — use the latest model available on OmwAI
`model_provider`	Custom provider name, must match `[model_providers.xxx]` below
`base_url`	Your OmwAI site address + `/v1` path
`requires_openai_auth`	Set to `true` for OpenAI-compatible authentication
`wire_api`	Set to `"responses"` to use OpenAI Responses API
`web_search_request`	Set to `true` to enable web search capability
`disable_response_storage`	Set to `true` to disable local response history storage

Configure auth.json

Create or edit auth.json with the API Key copied from your OmwAI dashboard:

{
  "OPENAI_API_KEY": "sk-your-api-token"
}

Replace sk-your-api-token with the token value you created in the OmwAI dashboard.

It's recommended to create a dedicated group token for Codex CLI, making it easier to monitor usage and apply rate limits from the OmwAI dashboard.

Verify the Configuration

After completing the two configuration steps above, run the following command in your terminal:

codex

If Codex CLI starts successfully and responds to your conversation, the configuration is complete.

On first launch, Codex CLI will ask about file read/write permissions. Choose "Allow Codex to directly modify files" for the best experience.

Switching Models

While Codex CLI is running, type /model to view and switch between available models.

Troubleshooting

Connection Failed

Check that your base_url is correct, ensure it ends with /v1, and verify that your OmwAI site is accessible.

Authentication Failed

Confirm the API Key in auth.json is valid. You can create a new token in the OmwAI dashboard and try again.

Model Unavailable

If the selected model is unavailable, check the channel status in the OmwAI dashboard, or use /model to switch to another model.