Documentation — AI API Integration Guide & SDK Reference

System Requirements

Requirement	Details
Operating System	macOS 12+, Ubuntu 20.04+ / Debian 10+, or Windows 11 via WSL2
Git (Optional)	2.23+ (Recommended for built-in PR assistant)
Memory (RAM)	Minimum 4 GB (8 GB recommended)
Node.js	Version 22+ is required

Step 1: Install Codex CLI

Choose one of the following installation methods:

npm (Universal)

npm install -g @openai/codex

# Or if you need the native package:
# npm install -g @openai/codex@native

codex --version

Homebrew (Recommended for macOS)

brew update
brew install codex
codex --version

If Codex fails to execute or your Node version is too old, please upgrade Node.js (Node 22+ is required) or use the Homebrew installation method.

Step 2: Codex Configuration

After installation, you need to configure Codex to connect to ValueAPI using your API key.

1. Obtain your API Key

2. Configure `config.toml`

Upon startup, Codex reads the config.toml file from ~/.codex/. If it doesn't exist, create it:

mkdir -p ~/.codex
nano ~/.codex/config.toml

Add the following configuration to config.toml:

model_provider = "valueapi"  # Set API provider
model = "gpt-5.4"          # Specify a Codex-supported model
model_reasoning_effort = "low" # Reasoning level: low, medium (default), high, minimal

# Provider Settings
[model_providers.valueapi]
name = "ValueAPI"
base_url = "https://api.valueapi.ai/v1"
env_key = "VALUEAPI_KEY"   # The environment variable name for your API key
wire_api = "chat"          # Use the /v1/chat/completions protocol
query_params = {}
request_max_retries = 4    # Max retries on failure
stream_max_retries = 10    # Max retries on stream interruption

# Optional: Define a profile for quick CLI switching
[profiles.valueapi]
model_provider = "valueapi"
model = "gpt-5.4"
approval_policy = "on-request"   # Ask for confirmation before execution
sandbox_mode = "workspace-write" # Allow writing to current workspace

3. Set API Key Environment Variable

You must add the VALUEAPI_KEY environment variable to your system. The value should be your ValueAPI key (starting with sk-).

Windows:

# Temporary (clears when terminal closes)
set VALUEAPI_KEY=sk-xxxxxx

# Permanent
setx VALUEAPI_KEY "sk-xxxxxx"

macOS / Linux:

Method 1: Permanent (Recommended)

# 1. Open your shell profile
nano ~/.bashrc   # For Bash
nano ~/.zshrc    # For Zsh (macOS default)

# 2. Add this line to the end of the file
export VALUEAPI_KEY="sk-xxxxxx"

# 3. Apply the changes
source ~/.bashrc # Or source ~/.zshrc

Method 2: Temporary

export VALUEAPI_KEY="sk-xxxxxx"

Verify Configuration:

# Windows (CMD)
echo %VALUEAPI_KEY%

# Windows (PowerShell)
echo $env:VALUEAPI_KEY

# macOS / Linux
echo $VALUEAPI_KEY

Step 3: Start Using Codex

Codex CLI Commands

# Ask a direct question
codex "Hello"

# Use a specific profile (if you defined multiple providers)
codex --profile valueapi "Hello"

Using Codex in VS Code

If you are using the Codex extension in VS Code, you must completely restart VS Code after configuring the environment variables for the changes to take effect.

Advanced Usage Tips

CLI Reference

Command	Purpose	Example
codex	Interactive TUI	codex
codex "..."	Initial prompt for interactive TUI	codex "fix lint errors"
codex exec "..."	Non-interactive "automation mode"	codex exec "explain utils.ts"

Non-interactive / CI Mode

Run Codex headlessly in pipelines. Here is an example GitHub Action step:

- name: Update changelog via Codex
run: |
npm install -g @openai/codex
export VALUEAPI_KEY="${{ secrets.VALUEAPI_KEY }}"
codex exec --full-auto "update CHANGELOG for next release"

Model Context Protocol (MCP)

You can configure the Codex CLI to use MCP servers by defining an mcp_servers section in ~/.codex/config.toml. Note that Codex uses TOML instead of JSON:

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }

References

Official Codex Configuration Documentation

OpenAI Codex Integration Guide