GPT-5.5 Codex Setup Guide: Windows, macOS, and Linux CLI Integration - Devuly | Smart Analytics for Developers & Projects

This guide focuses on connecting GPT-5.5 Codex through the CLI in domestic network environments, addressing common issues around API endpoints, authentication setup, and inconsistent installation steps across Windows, macOS, and Linux. The core goal is to enable Codex to enter your project, read and write code, run tests, and continue fixing issues iteratively. Keywords: Codex CLI, API Key, config.toml.

Table of Contents

Technical specifications at a glance

Parameter	Description
Language	Node.js / Shell / PowerShell / JSON / TOML
Protocol	HTTP integration based on a compatible API
Stars	Not provided in the source
Core dependencies	Node.js 22+, npm, Git, @openai/codex

Codex is well suited for long-context engineering tasks

Codex is not just a code completion plugin. It is an AI coding agent designed for terminal-based workflows. It can enter a project directory, read files, understand module relationships, execute commands, modify code, and continue iterating based on test results.

These capabilities are especially useful for cross-file analysis, refactoring, adding tests, troubleshooting errors, and organizing documentation. For developers in domestic environments, the real barrier is usually not the CLI itself, but correctly combining an available API endpoint, the right model name, and a valid local configuration.

Verify that your local environment meets the requirements first

node -v
npm -v
# First confirm that Node.js and npm are available to avoid installation failures later

Use these commands to confirm that the base environment required to run Codex CLI is already in place.

The minimum working setup in domestic environments consists of two parts

The first part is installing Codex CLI. The second part is preparing the .codex configuration directory under ~/.codex or your user home directory. There are only two core files: auth.json and config.toml.

auth.json stores the API key, while config.toml declares the provider, model, reasoning level, and API endpoint. Both files are required, and they must live in the same configuration directory.

A minimal authentication file can look like this

{
  "OPENAI_API_KEY": "sk-xxx"
}

This configuration provides the API key to Codex CLI. Replace it with your real token in production use.

The installation flow is mostly consistent across all three platforms, but command details differ

Windows users typically install through PowerShell, while macOS and Linux follow a more standard shell-based workflow. If npm downloads are slow, you can switch to a domestic mirror. This only affects package download speed and does not affect model requests.

npm install -g @openai/codex
# Install Codex CLI globally
npm install -g @openai/codex --registry=https://registry.npmmirror.com
# Use a mirror to speed up installation in domestic network environments
codex --version
# Verify that the CLI is available in PATH

Use these commands to install Codex CLI and verify that your terminal can invoke it directly.

Windows requires extra attention to the user directory and file extensions

A typical Windows path is C:\Users\YourUsername\.codex. The most common issue is not incorrect file content, but files being saved as config.toml.txt or auth.json.txt, which prevents the CLI from recognizing them.

After entering your project, run codex, then use /status to check whether the current model, provider, and authentication settings are active. If the command does not exist, first verify that the global npm bin path has been added to your environment variables.

The main difference on macOS and Linux is how Node.js is installed

On macOS, you usually only need to create ~/.codex and write the configuration files. On Linux, especially Ubuntu or Debian, you often need to install Node.js 22 or later first.

mkdir -p ~/.codex
# Create the Codex configuration directory
vi ~/.codex/auth.json
# Write the API key
vi ~/.codex/config.toml
# Write the provider and model configuration

Use these commands to create the local configuration directory and files required by Codex on Unix-like systems.

`config.toml` determines whether requests can actually reach the API

The most critical fields include model_provider, model, preferred_auth_method, base_url, and wire_api. The most common source of errors is a mismatch between the base_url path and the model name.

model_provider = "codex_api"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.codex_api]
name = "Codex API"
base_url = "https://codex.tokenshop.pro/v1"
wire_api = "responses"
# base_url is only an example and must match the actual value provided by your console

This configuration defines which model Codex uses, which API entry point it targets, and which wire protocol it uses to send requests.

On first launch, you should validate in read-only mode before changing code

After setup is complete, do not immediately ask Codex to refactor a large project. A safer approach is to inspect status first, then ask it to analyze the repository structure, startup flow, and test workflow in read-only mode.

/status
/model
Do not modify any files yet. Read the current project and explain the tech stack, directory structure, startup process, testing workflow, and core modules.
# Validate model access and context understanding before entering the modification phase

Use these prompts to verify that the configuration chain is working, the model is available, and project understanding quality is acceptable.

Small, incremental trial runs are more reliable than one-shot rewrites

If the read-only analysis is correct, next ask Codex to propose a plan before editing files. This reduces the blast radius of unintended changes and makes human review easier.

First explain which files you plan to modify and why. Do not change any code yet.
Based on the plan above, add tests, run the relevant tests after modification, and summarize the files you changed.
# Plan first, then execute—this is the key habit for controlling AI change risk

Use these prompts to establish a safer collaboration rhythm: confirm the plan first, then authorize actual changes.

Most common failures fall into four categories

The first category is that the codex command does not exist, which is usually related to the global npm path not being added to PATH. The second category is an invalid API Key, typically caused by an incorrect filename, a misspelled key name, or extra whitespace in the token.

The third category is model not found, which usually means the current token does not support gpt-5.5, or the local model name does not match the value shown in your provider console. The fourth category is that the CLI launches but requests fail. In that case, first verify whether base_url includes the correct path and whether wire_api remains set to responses.

Use Git to keep changes auditable

git init
# Initialize version control in the project directory so AI-generated changes can be rolled back
git diff
# Review which files Codex changed and inspect the exact differences

Use these commands to place Codex-generated changes into an auditable and reversible engineering workflow.

FAQ

Q1: Why does Codex still report an authentication failure even though I created `auth.json`?

A: First verify that the file is located in the .codex directory under your user home directory. Then confirm that the key name is exactly OPENAI_API_KEY, and rule out leading or trailing spaces, stray newlines, or an expired token.

Q2: How should I fix `model not found` for `gpt-5.5`?

A: First use /model to inspect the models currently available to your account, then confirm that your token actually supports that model. It is also a good idea to upgrade the CLI to the latest version to avoid compatibility issues with older local protocol implementations.

Q3: After the initial setup, how can I tell whether Codex is ready for real projects?

A: At minimum, complete these three checks: /status works correctly, /model recognizes the target model, and read-only analysis can accurately explain the project structure. Once all three pass, you can move on to small-scale test additions or bug fixes.

Core summary

This guide reconstructs the cross-platform GPT-5.5 Codex setup workflow for domestic environments, covering Node.js, Codex CLI, auth.json, config.toml, base_url, and first-run validation. It helps developers complete a local integration that is functional, debuggable, and reproducible.