Codex CLI

What is Codex CLI?

Codex CLI is OpenAI's open-source command-line coding agent that runs locally from your terminal. It can read, change, and run code on your machine in the selected directory, providing a powerful AI-powered development assistant directly in your workflow. Built to help developers write features, answer questions about codebases, fix bugs, and propose pull requests for review, Codex CLI brings autonomous AI assistance to your local development environment.

Key features:

• Local Code Execution Runs directly on your machine, reading and modifying files in your project directory with full access to your local environment.

• Interactive Terminal Mode Supports interactive conversations, allowing you to resume previous sessions and iterate on tasks through natural-language interactions.

• Multi-Model Support Works with various AI models and supports custom model providers via configuration file, enabling flexibility in choosing your preferred LLM backend.

• Code Generation & Refactoring Instantly generates code snippets, refactors functions, and implements new features based on your prompts.

• Intelligent Reasoning Leverages advanced reasoning capabilities to understand complex codebases and provide context-aware solutions.

• Image Input Support Can process image inputs for visual context, enabling more comprehensive understanding of design specifications or diagrams.

• Web Search Integration Built-in web search capability to find relevant documentation and solutions while coding.

• Local Code Review Performs automated code reviews on your local changes before committing.

• Version Control Integration Everything runs under version control, sandboxed and limited to the selected working directory for safety.

• Custom Provider Configuration Supports custom model providers via config file without requiring source code modifications.

---

How to Connect Codex CLI with nexos.ai

To connect nexos.ai API with Codex CLI, follow these steps:

1. Install Codex CLI

Option A: Using npm (All platforms)

Install the Codex CLI globally using npm:

npm install -g @openai/codex

Option B: Using Homebrew (macOS)

On macOS, you can also install Codex CLI using Homebrew:

brew install codex

2. Set Up Your API Key

Export your API key as an environment variable. Add this to your shell profile (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile):

export NEXOS_AI_API_KEY="your-team-api-key-here"

Then reload your shell configuration:

source ~/.bashrc  # or ~/.zshrc depending on your shell

3. Configure Codex CLI

Create or edit the configuration file at ~/.codex/config.toml:

model = "<your-model-uuid-or-name>"

[model_providers.nexosai]
name = "nexos.ai"
base_url = "https://api.nexos.ai/v1"
env_key = "NEXOS_AI_API_KEY"
# Use "responses" for models supporting the responses endpoint (e.g., OpenAI models)
# Use "chat" for models that do not support the responses endpoint (e.g., some Claude models)
wire_api = "responses"
model_verbosity = "high"

Configuration Options Explained:

Option	Description
model	The model UUID or name from nexos.ai that you want to use as default
name	Display name for the provider
base_url	nexos.ai API endpoint: https://api.nexos.ai/v1
env_key	The environment variable name containing your API key
wire_api	API format - use "responses" for models supporting the responses endpoint, or "chat" for models that only support the chat completions endpoint
model_verbosity	Level of model output detail ("high", "medium", or "low")

Note: If you encounter issues with certain models, try switching wire_api from "responses" to "chat". Some models (particularly non-OpenAI models) may not support the responses endpoint and require the chat completions API instead.

4. (Optional) Configure Project Trust Levels

For specific project directories, you can set trust levels:

model = "<your-model-uuid-or-name>"

[projects."/Users/[user]/code/your-project"]
trust_level = "untrusted"

[model_providers.nexosai]
name = "nexos.ai"
base_url = "https://api.nexos.ai/v1"
env_key = "NEXOS_AI_API_KEY"
# Use "responses" for models supporting the responses endpoint (e.g., OpenAI models)
# Use "chat" for models that do not support the responses endpoint (e.g., some Claude models)
wire_api = "responses"
model_verbosity = "high"

Trust levels:

• untrusted - Codex will ask for confirmation before executing commands

• trusted - Allows automatic execution within the project scope

5. Start Using Codex CLI

Navigate to your project directory and run Codex CLI with the nexos.ai provider:

codex --config model_provider="nexosai"

Or run with a specific prompt:

codex --config model_provider="nexosai" "explain this codebase structure"

Note: The --config model_provider="nexosai" flag tells Codex CLI to use the nexos.ai provider defined in your configuration file.

---

Using Different Models

Fetching Available Models

You can retrieve the list of all available models for you using the API:

curl -X GET "https://api.nexos.ai/v1/models" \
  -H "Authorization: Bearer $NEXOS_AI_API_KEY"

API Reference: See the full API documentation at Gateway API | nexos.ai documentation

Configuring Models

You can use either the model name or UUID in your configuration. Update the model value in your ~/.codex/config.toml:

# Using model UUID
model = "6ff8398f-9276-4756-a9f2-f66b069f1d32"

# Or any other model available in your nexos.ai workspace
model = "claude-opus-4-1-20250805"

---

Troubleshooting

Issue	Solution
Authentication errors	Verify NEXOS_AI_API_KEY is correctly set in your environment
Model not found	Use the models API endpoint to fetch available models and confirm the model name/UUID exists in your workspace
Config not loading	Ensure the config file is at ~/.codex/config.toml with correct TOML syntax
Provider not recognized	Make sure to use --config model_provider="nexosai" when running codex
API format errors	Try switching wire_api from "responses" to "chat" if your model doesn't support the responses endpoint

---

Benefits of Using nexos.ai with Codex CLI

By routing Codex CLI through nexos.ai, you gain access to:

• Multiple LLMs - Switch between different models (Claude, GPT, and others) without changing configurations

• Cost Tracking - Monitor AI spend with usage visibility across teams

• Intelligent Caching - Reduce redundant API calls and optimize costs

• Centralized Logging - Full observability for every prompt and operation

• Load Balancing - Automatic failover to keep your development workflow reliable