> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Connect Codex CLI to EvoLink.AI

## Overview

<img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/codex-interface.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=576a53ca051d07b3622d3fb16570560d" alt="Codex CLI Interface" width="1730" height="923" data-path="images/integration-guide/codex-interface.png" />

Codex CLI is OpenAI's official command-line tool for code-related tasks in the terminal. Compared to general chat tools, it emphasizes engineering-ready output with clearer, actionable code changes.
By integrating Codex CLI with **EvoLink API**, you can access EvoLink's models (such as **GPT series**) through a unified OpenAI-compatible interface with one key and one base URL.

## Prerequisites

Before configuring, make sure you have:

### 1. Install Node.js and npm

**Why needed?** Node.js is the runtime environment for CLI tools (like installing WeChat on your phone to chat, you need to install Node.js on your computer to run CLI tools).

**If already installed:** Run `node -v` and `npm -v` to check version. If v20+, skip this step.

**First-time installation:**

* Download and install from [Node.js official website](https://nodejs.org/) (recommend LTS version)
* If you're unfamiliar with the installation process, refer to [Runoob - Node.js Installation Guide](https://www.runoob.com/nodejs/nodejs-install-setup.html)
* Recommended: **Node.js v20 or higher**
* Verify installation:

```bash theme={null}
node -v
npm -v
```

<img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/claude-node-npm-verify.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=13be4f60f117fca3024b2b2c1d0fd208" alt="Node.js and npm version verification" width="1730" height="923" data-path="images/integration-guide/claude-node-npm-verify.png" />

### 2. Get EvoLink API Key

* Log in to [EvoLink Dashboard](https://evolink.ai/dashboard)
* Find API Keys in the dashboard, click 'Create New Key' button, then copy the generated Key
* API Key usually starts with `sk-`

## Step 1: Install Codex CLI

<Note>
  **Tip:** If you don't know how to open a command line terminal, see [FAQ - How to open command line terminal](#13-how-to-open-command-line-terminal)
</Note>

### 1. Global Installation

```bash theme={null}
npm install -g @openai/codex
```

**Expected result:** Download info scrolling, ending with `added XX packages` (takes 1-3 minutes).

**If error occurs:** `permission denied` means Windows needs "Run as administrator" PowerShell, macOS/Linux add `sudo` before command.

### 2. Verify Installation

```bash theme={null}
codex --version
```

**Success indicator:** Shows version number (e.g., `1.x.x`).

<img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/codex-version.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=02d0328b87db204a5c64cf7b5b7a30c2" alt="Codex CLI Version" width="1730" height="923" data-path="images/integration-guide/codex-version.png" />

## Step 2: Configure EvoLink API

Codex CLI supports a custom Provider via config file, no source code modification needed.

<Tabs>
  <Tab title="Method 1: GUI Operation">
    ### 1. Open Config Directory

    <Tabs>
      <Tab title="Windows">
        Press `Win + R`, paste the following, then press Enter to open the Codex config directory:

        ```
        %userprofile%\.codex
        ```

        <img src="https://mintcdn.com/muyutechnology/hdDK-GS-iVpfdhZR/images/integration-guide/encodexwin-r.png?fit=max&auto=format&n=hdDK-GS-iVpfdhZR&q=85&s=c0ceff6634145bbb3ab064fa03a66071" alt="Windows Win+R open terminal" width="568" height="334" data-path="images/integration-guide/encodexwin-r.png" />
      </Tab>

      <Tab title="macOS">
        In Finder, press `Command + Shift + G`, paste the following path, then press Enter:

        ```
        ~/.codex
        ```
      </Tab>

      <Tab title="Linux">
        Access the config directory in your file manager:

        ```
        ~/.codex
        ```
      </Tab>
    </Tabs>

    <img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/codex-config-env-en.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=1f36780bdb4aa8721817aecef1bf9588" alt="Codex CLI config environment" width="3648" height="1184" data-path="images/integration-guide/codex-config-env-en.png" />

    ### 2. Edit config.toml

    Find the `config.toml` file in the config directory and edit it with the following content:

    ```toml theme={null}
    model = "gpt-5.2"
    model_reasoning_effort = "medium"
    model_provider = "evolink"

    [model_providers.evolink]
    name = "EvoLink API"
    base_url = "https://direct.evolink.ai/v1"
    env_key = "OPENAI_API_KEY"
    wire_api = "responses"
    ```

    **⚠️ Important:**

    * **Copy completely** without missing any symbols
    * Replace `"your-evolink-api-key"` with actual API Key
    * TOML format is sensitive to indentation and symbols
  </Tab>

  <Tab title="Method 2: One-Command Creation">
    <Tabs>
      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        @"
        model = "gpt-5.2"
        model_reasoning_effort = "medium"
        model_provider = "evolink"

        [model_providers.evolink]
        name = "EvoLink API"
        base_url = "https://direct.evolink.ai/v1"
        env_key = "OPENAI_API_KEY"
        wire_api = "responses"
        "@ | Out-File -FilePath "$env:USERPROFILE\.codex\config.toml" -Encoding utf8
        ```

        <img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/codex-one-command-config-win.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=fd396d27dcdf6c2db914c1d39e542bf9" alt="Codex one-command configuration" width="1730" height="923" data-path="images/integration-guide/codex-one-command-config-win.png" />
      </Tab>

      <Tab title="macOS / Linux">
        ```bash theme={null}
        cat > ~/.codex/config.toml << 'EOF'
        model = "gpt-5.2"
        model_reasoning_effort = "medium"
        model_provider = "evolink"

        [model_providers.evolink]
        name = "EvoLink API"
        base_url = "https://direct.evolink.ai/v1"
        env_key = "OPENAI_API_KEY"
        wire_api = "responses"
        EOF
        ```
      </Tab>
    </Tabs>

    After running the command, the config file will be automatically created and written.
  </Tab>
</Tabs>

```toml theme={null}
model = "gpt-5.2"
model_reasoning_effort = "medium"
model_provider = "evolink"

[model_providers.evolink]
name = "EvoLink API"
base_url = "https://direct.evolink.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

Config fields:

* `model`: default model name
* `model_reasoning_effort`: reasoning depth (adjust as needed)
* `model_provider`: provider name that matches the section below
* `base_url`: EvoLink API endpoint
* `env_key`: environment variable name for the API key
* `wire_api`: must be `responses`

### 2. Configure API Key

<Tabs>
  <Tab title="Windows PowerShell">
    **Temporary (current session only)**

    ```powershell theme={null}
    $env:OPENAI_API_KEY = "your-evolink-api-key"
    ```

    **Permanent**

    ```powershell theme={null}
    [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-evolink-api-key", "User")
    ```

    Restart the terminal for changes to take effect.

    **Verify Configuration**

    ```powershell theme={null}
    echo $env:OPENAI_API_KEY
    ```

    <img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/codex-check-env.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=f455f371105f4bba6a0b898f247129dc" alt="Check if environment variable is added successfully" width="1730" height="923" data-path="images/integration-guide/codex-check-env.png" />

    If it outputs your API Key, the configuration is successful.
  </Tab>

  <Tab title="macOS / Linux">
    **Temporary (current session only)**

    ```bash theme={null}
    export OPENAI_API_KEY="your-evolink-api-key"
    ```

    **Permanent**
    Edit `~/.bashrc` or `~/.zshrc`, add:

    ```bash theme={null}
    export OPENAI_API_KEY="your-evolink-api-key"
    ```

    Then run `source ~/.bashrc` or `source ~/.zshrc` to apply, or restart the terminal.

    **Verify Configuration**

    ```bash theme={null}
    echo $OPENAI_API_KEY
    ```

    If it outputs your API Key, the configuration is successful.
  </Tab>
</Tabs>

## Step 3: Start Using Codex CLI

### 1. Enter working directory

```shell theme={null}
cd your-working-directory
```

**Note:** Replace `your-working-directory` with actual path

### 2. Interactive mode

```shell theme={null}
codex
```

<img src="https://mintcdn.com/muyutechnology/aVl9y2uT7NNwpwBy/images/integration-guide/codex-interface.png?fit=max&auto=format&n=aVl9y2uT7NNwpwBy&q=85&s=576a53ca051d07b3622d3fb16570560d" alt="Codex CLI Interface" width="1730" height="923" data-path="images/integration-guide/codex-interface.png" />

### 3. Verify configuration

```shell theme={null}
codex "Who are you"
```

**Success indicators:**

* See AI response text (several lines)
* **No** errors like `401`, `403`, `API Key invalid`

**If you see errors:**

* `401 Unauthorized`: API Key not set or invalid → Check environment variable
* `403 Forbidden`: Insufficient API Key permissions → Verify API Key
* `Network error`: Network issue → Check connection

## FAQ

### 1. What is Codex CLI and what is it used for?

Codex CLI is OpenAI's official command-line tool focused on code-related tasks. It emphasizes engineering-ready output with clearer, actionable code changes.

### 2. How do I verify installation and configuration on first use?

Run these commands in sequence:

* `node -v` and `npm -v`: Confirm Node.js and npm are installed
* `codex --version`: Confirm Codex CLI is installed
* `codex "Who are you"`: Confirm API configuration is correct

### 3. What's the difference between interactive mode and single command mode?

* **Interactive mode**: Run `codex` to enter continuous conversation for multi-turn interactions
* **Single command mode**: Run `codex "question"` to get a single response and exit

### 4. Will Codex CLI automatically read or upload my local files and code?

No. Codex CLI only reads file content when you explicitly reference or authorize it. It's recommended to use it in a dedicated project folder.

### 5. How do I use Codex CLI to analyze local file content?

In interactive mode, you can reference files by:

* Typing the file path for Codex to read
* Dragging files into the terminal window
* Copy and pasting file content

### 6. Does Codex CLI support Chinese input and output?

Yes, fully supported.

### 7. No output after execution—what could be the cause?

Common causes include:

* Network connection issues
* Invalid API Key or insufficient balance
* Incorrect `base_url` configuration
* Firewall or proxy blocking requests

### 8. Why don't my config changes take effect?

* Restart your terminal
* Check `config.toml` syntax (TOML format)
* Verify config file path:
  * Windows: `C:\Users\{username}\.codex\config.toml`
  * macOS / Linux: `~/.codex/config.toml`

### 9. What causes 401/403 errors?

* **401 error**: `OPENAI_API_KEY` not set or invalid
* **403 error**: Insufficient permissions or expired key
* Check that `env_key` matches your environment variable name

### 10. What scenarios is Codex CLI suited for?

**Suited for:**

* Code writing, debugging, and refactoring
* Quick Q\&A in command-line environments
* File content analysis

**Not suited for:**

* Complex GUI interactions
* Real-time collaborative editing

### 11. How do I switch models?

Open the configuration file `config.toml` (located at `~/.codex/config.toml` or `C:\Users\{username}\.codex\config.toml`), and modify the `model` field:

```toml theme={null}
model = "gpt-5.2"  # Change to your desired model name
```

Save the file and restart Codex CLI for changes to take effect.

### 12. How do I upload images?

* Option 1: Reference the image path
* Option 2: Drag and drop an image into the terminal
* Option 3: Paste an image directly

All methods require user action—Codex CLI will not automatically read or upload local images.

### 13. How to open command line terminal?

<Tabs>
  <Tab title="Windows">
    * Method 1: Press `Win + R`, type `cmd` or `powershell`, then press Enter
    * Method 2: Search for "Command Prompt" or "PowerShell" in the Start menu
    * Method 3: Hold Shift and right-click in a folder, select "Open PowerShell window here"
  </Tab>

  <Tab title="macOS">
    * Method 1: Press `Command + Space` to open Spotlight, type `Terminal`, then press Enter
    * Method 2: Go to "Applications" → "Utilities" → "Terminal"
  </Tab>

  <Tab title="Linux">
    * Method 1: Press `Ctrl + Alt + T` shortcut
    * Method 2: Search for "Terminal" in the application menu
  </Tab>
</Tabs>

## Notes

<Warning>
  Run Codex CLI in a dedicated project folder. Avoid running it in sensitive directories (such as system folders or directories containing credentials). Codex CLI operates starting from the current working directory.
</Warning>

<Tip>
  The `wire_api` in config must be set to `"responses"`. `"chat"` is deprecated.
</Tip>