Codex integration guide

Developer toolCLI toolUpdated: 2026-06-29

Introduction

Codex is OpenAI's terminal AI coding assistant, providing intelligent code assistance through a command-line interface. Using the SeaWhale AI OpenAI-compatible endpoint, you can run GPT models inside Codex for a high-quality coding experience.

Key capabilities

💻 Code generation — write code from a description
🐛 Debugging — locate and fix bugs quickly
♻️ Refactoring — improve code structure and performance
📝 Documentation — add comments and docs to your code
🔍 Code explanation — make sense of complex logic
🚀 Many languages — Python, JavaScript, Java, Go and more

Why SeaWhale AI?

Advantage	Description
💰 Flexible billing	Pay as you go, no subscription required
🌐 Direct access	Reachable directly, no extra network setup
⚡ High performance	Low latency, fast responses
🔒 Data security	Code is not stored, protecting your privacy
🆓 New user credit	New accounts receive free credit
🔄 Many models	One configuration, switch freely between GPT versions

Supported models

Codex connects to SeaWhale AI through the OpenAI-compatible endpoint, supporting:

Model list

Family	Model name	Strengths	Best for
GPT	`gpt-5.5`, `gpt-4.1`	• Strong all round • Accurate reasoning	Complex tasks, architecture

Protocol compatibility

Current Codex versions support only the Responses API, and on SeaWhale AI only GPT-family models implement that protocol. For other models (Claude, DeepSeek, Qwen), use a different client such as Claude Code.

Choosing a model

Recommended main model: gpt-5.5 (strongest all round, high code quality)
Recommended fast model: gpt-4.1 (better value, faster responses)
Full model list: see the model list

Before you begin

1. Get a SeaWhale AI API key

Open the SeaWhale AI console
Sign up and log in
Generate an API key on the API management page
Make sure your account has enough balance or free credit

New user credit

New SeaWhale AI accounts receive free starter credit:

✅ Usable across all model inference services

2. System requirements

Item	Requirement
Operating system	macOS 10.15+, Windows 10+, Linux
Node.js	v18.0+
npm	v9.0+
Terminal	A modern terminal with color support

Installation

1. Install the Codex CLI

macOS/LinuxWindows

bash

# Install the latest version globally with npm
npm install -g @openai/codex

# Verify the installation
codex --version

powershell

# Install the latest version globally with npm
npm install -g @openai/codex

# Verify the installation
codex --version

Installation notes

If you hit permission errors, you may need sudo (macOS/Linux)
On Windows, run PowerShell as administrator
To speed up npm, you can switch registries: npm config set registry https://registry.npmmirror.com

Version requirements

Install the latest Codex release, which uses the Responses API by default. SeaWhale AI requires the Responses protocol; the wire_api = "chat" mode from older versions (such as 0.80.0) is no longer supported.

2. Point Codex at SeaWhale AI

Codex reads its endpoint from ~/.codex/config.toml and takes credentials from the OPENAI_API_KEY environment variable.

Edit the config file

Open (or create) ~/.codex/config.toml and add:

toml

model_provider = "SeaWhaleAI"
model = "gpt-5.5"

[model_providers.SeaWhaleAI]
name = "SeaWhaleAI"
base_url = "https://api.seawhaleai.com/v2"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

What each setting does

model_provider: your provider identifier, matching the [model_providers.xxx] section below
model: the default model — any GPT-family model ID that supports the Responses protocol
base_url: the SeaWhale AI OpenAI-compatible endpoint
wire_api: must be responses; newer Codex versions no longer support chat

Set the environment variable

Set OPENAI_API_KEY to your SeaWhale AI API key (not an official OpenAI key).

Zsh (macOS default)BashWindows PowerShell

bash

# Replace sk-xxx with your SeaWhale AI API key
echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

bash

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

powershell

# Current session only
$env:OPENAI_API_KEY = "sk-xxxxxxxxxxxxxxxx"

# Persistent (user level)
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxxxxxxxxxxxxxxx", "User")

Check which shell you are using with:

bash

echo $SHELL

3. Verify the configuration

Open a new terminal window and start Codex:

bash

codex

If the chat interface opens and a simple question gets a response, the configuration works.

bash

> Write a Python function that checks whether a string is a palindrome

Usage guide

Basics

1. Start Codex

bash

# Change into your project directory
cd my-project

# Start Codex
codex

2. Switching models

Change the model field in ~/.codex/config.toml:

toml

model = "gpt-5.5"       # Recommended default, strongest all round
# model = "gpt-4.1"     # Better value, faster responses

Save the file and restart codex for the change to take effect.

3. Common commands

Command	What it does
`/help`	Show help
`/clear`	Clear conversation history
`/exit`	Quit

Saving tokens

Using Codex thoughtfully can noticeably cut token usage and cost.

1. Reduce irrelevant file scanning

Best practices

✅ Start Codex inside the specific project directory
✅ Use .gitignore to exclude unnecessary files
✅ Delete or move large binary files
✅ Avoid starting in your home directory or a folder containing many projects

2. Pick the right model

Task type	Recommended model	Why
Simple code generation	`gpt-4.1`	Fast and inexpensive
Complex algorithms	`gpt-5.5`	Accurate, reliable reasoning
Architecture design	`gpt-5.5`	Strongest all round

3. Give precise instructions

❌ Vague	✅ Precise
"Optimize this code"	"Refactor `get_user_list` in user.py to use a list comprehension"
"Fix this for me"	"Add error handling at line 45 of index.js to catch API failures"
"Something's wrong"	"Fix the division-by-zero in calculate.py and add input validation"

FAQ

Q1: I get `wire_api = chat is no longer supported`

Cause: newer Codex versions no longer support wire_api = "chat".

Fix: set wire_api = "responses" in ~/.codex/config.toml and switch model to a GPT-family model that supports the Responses protocol on SeaWhale AI.

Q2: I get `401 Unauthorized`

Possible causes:

The API key is misspelled or contains stray spaces or characters
You used an official OpenAI key instead of a SeaWhale AI key
Your balance is exhausted, or the key has been disabled

Fix:

Copy your full SeaWhale AI API key again
Confirm the environment variable is set: echo $OPENAI_API_KEY
Check the key's status in the SeaWhale AI console
Reset the API key and reconfigure if necessary

Q3: I get `404 Not Found`

Cause: base_url or wire_api is wrong.

Fix:

Confirm base_url = "https://api.seawhaleai.com/v2" (note the trailing /v2)
Confirm the model name exists in the model list
Confirm the model is in the GPT family (other models do not yet support the Responses protocol)

Q4: The environment variable does not take effect

Fix:

Confirm you edited the file for your current shell (~/.zshrc for Zsh, ~/.bashrc for Bash)
Run source ~/.zshrc (or ~/.bashrc) to apply it
Open a new terminal window and try again
Verify with echo $OPENAI_API_KEY

Q5: Can I configure several providers at once?

Yes. Define multiple [model_providers.xxx] sections in ~/.codex/config.toml and switch between them with model_provider:

toml

model_provider = "SeaWhaleAI"
model = "gpt-5.5"

[model_providers.SeaWhaleAI]
name = "SeaWhaleAI"
base_url = "https://api.seawhaleai.com/v2"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[model_providers.OpenAI_Official]
name = "OpenAI_Official"
base_url = "https://api.openai.com/v2"
env_key = "OPENAI_OFFICIAL_KEY"
wire_api = "responses"

Q6: How is my code kept private?

SeaWhale AI commits to:

🔒 No code storage — deleted immediately after the request is processed
🔒 End-to-end encryption — encrypted throughout transit
🔒 No training use — your code is never used to train models

Security recommendations

Do not include secrets (passwords, keys) in your code
For extremely sensitive projects, consider a local model
Review API key usage regularly

📚 Quick start — SeaWhale AI API basics
🔧 API reference — the complete API documentation
🎯 Model list — every available model
🛠️ Claude Code guide — the official Claude CLI
🛠️ Qwen Code guide — Qwen Code integration

Codex integration guide ​

Introduction ​

Key capabilities ​

Why SeaWhale AI? ​

Supported models ​

Model list ​

Before you begin ​

1. Get a SeaWhale AI API key ​

2. System requirements ​

Installation ​

1. Install the Codex CLI ​

2. Point Codex at SeaWhale AI ​

Edit the config file ​

Set the environment variable ​

3. Verify the configuration ​

Usage guide ​

Basics ​

1. Start Codex ​

2. Switching models ​

3. Common commands ​

Saving tokens ​

1. Reduce irrelevant file scanning ​

2. Pick the right model ​

3. Give precise instructions ​

FAQ ​

Q1: I get wire_api = chat is no longer supported ​

Q2: I get 401 Unauthorized ​

Q3: I get 404 Not Found ​

Q4: The environment variable does not take effect ​

Q5: Can I configure several providers at once? ​

Q6: How is my code kept private? ​

Related resources ​

Codex integration guide

Introduction

Key capabilities

Why SeaWhale AI?

Supported models

Model list

Before you begin

1. Get a SeaWhale AI API key

2. System requirements

Installation

1. Install the Codex CLI

2. Point Codex at SeaWhale AI

Edit the config file

Set the environment variable

3. Verify the configuration

Usage guide

Basics

1. Start Codex

2. Switching models

3. Common commands

Saving tokens

1. Reduce irrelevant file scanning

2. Pick the right model

3. Give precise instructions

FAQ

Q1: I get `wire_api = chat is no longer supported`

Q2: I get `401 Unauthorized`

Q3: I get `404 Not Found`

Q4: The environment variable does not take effect

Q5: Can I configure several providers at once?

Q6: How is my code kept private?

Related resources