> ## 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

> Codex CLI를 EvoLink.AI에 연결하기

## 개요

<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는 터미널에서 코드 관련 작업을 수행하기 위한 OpenAI의 공식 커맨드라인 도구입니다. 일반적인 채팅 도구와 비교하여, 더 명확하고 실행 가능한 코드 변경 사항을 제공하는 엔지니어링 수준의 출력에 중점을 둡니다.
Codex CLI를 **EvoLink API**와 통합하면, 하나의 키와 하나의 Base URL로 OpenAI 호환 인터페이스를 통해 EvoLink의 모델(예: **GPT 시리즈**)에 접근할 수 있습니다.

## 사전 준비

설정하기 전에 다음 사항을 확인하세요:

### 1. Node.js 및 npm 설치

**왜 필요한가요?** Node.js는 CLI 도구의 런타임 환경입니다 (휴대폰에 카카오톡을 설치해야 채팅할 수 있듯이, 컴퓨터에 Node.js를 설치해야 CLI 도구를 실행할 수 있습니다).

**이미 설치된 경우:** `node -v`와 `npm -v`를 실행하여 버전을 확인하세요. v20 이상이면 이 단계를 건너뛰세요.

**처음 설치하는 경우:**

* [Node.js 공식 웹사이트](https://nodejs.org/)에서 다운로드하여 설치하세요 (LTS 버전 권장)
* 설치 과정이 익숙하지 않다면 [Runoob - Node.js 설치 가이드](https://www.runoob.com/nodejs/nodejs-install-setup.html)를 참고하세요
* 권장: **Node.js v20 이상**
* 설치 확인:

```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. EvoLink API Key 발급

* [EvoLink Dashboard](https://evolink.ai/dashboard)에 로그인하세요
* 대시보드에서 API Keys를 찾아 '새 키 생성' 버튼을 클릭한 후, 생성된 Key를 복사하세요
* API Key는 보통 `sk-`로 시작합니다

## Step 1: Codex CLI 설치

<Note>
  **팁:** 커맨드라인 터미널을 여는 방법을 모르시면 [FAQ - 커맨드라인 터미널 여는 방법](#13-커맨드라인-터미널-여는-방법)을 참고하세요
</Note>

### 1. 전역 설치

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

**예상 결과:** 다운로드 정보가 스크롤되며, 마지막에 `added XX packages`가 표시됩니다 (1\~3분 소요).

**오류 발생 시:** `permission denied`이 나타나면 Windows에서는 "관리자 권한으로 실행"한 PowerShell이 필요하고, macOS/Linux에서는 명령어 앞에 `sudo`를 추가하세요.

### 2. 설치 확인

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

**성공 표시:** 버전 번호가 표시됩니다 (예: `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: EvoLink API 설정

Codex CLI는 설정 파일을 통해 커스텀 Provider를 지원하며, 소스 코드 수정이 필요 없습니다.

<Tabs>
  <Tab title="방법 1: GUI 조작">
    ### 1. 설정 디렉토리 열기

    <Tabs>
      <Tab title="Windows">
        `Win + R`을 누르고, 아래 내용을 붙여넣은 후 Enter를 눌러 Codex 설정 디렉토리를 여세요:

        ```
        %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">
        Finder에서 `Command + Shift + G`를 누르고, 아래 경로를 붙여넣은 후 Enter를 누르세요:

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

      <Tab title="Linux">
        파일 관리자에서 설정 디렉토리에 접근하세요:

        ```
        ~/.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. config.toml 편집

    설정 디렉토리에서 `config.toml` 파일을 찾아 아래 내용으로 편집하세요:

    ```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"
    ```

    **⚠️ 중요:**

    * **빠짐없이 완전히 복사**하세요
    * `"your-evolink-api-key"`를 실제 API Key로 교체하세요
    * TOML 형식은 들여쓰기와 기호에 민감합니다
  </Tab>

  <Tab title="방법 2: 한 줄 명령어로 생성">
    <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>

    명령어를 실행하면 설정 파일이 자동으로 생성되고 작성됩니다.
  </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"
```

설정 필드 설명:

* `model`: 기본 모델 이름
* `model_reasoning_effort`: 추론 깊이 (필요에 따라 조정)
* `model_provider`: 아래 섹션과 일치하는 Provider 이름
* `base_url`: EvoLink API 엔드포인트
* `env_key`: API Key의 환경 변수 이름
* `wire_api`: 반드시 `responses`여야 합니다

### 2. API Key 설정

<Tabs>
  <Tab title="Windows PowerShell">
    **임시 (현재 세션만)**

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

    **영구 설정**

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

    변경 사항을 적용하려면 터미널을 재시작하세요.

    **설정 확인**

    ```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" />

    API Key가 출력되면 설정이 완료된 것입니다.
  </Tab>

  <Tab title="macOS / Linux">
    **임시 (현재 세션만)**

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

    **영구 설정**
    `~/.bashrc` 또는 `~/.zshrc`를 편집하여 다음을 추가하세요:

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

    그런 다음 `source ~/.bashrc` 또는 `source ~/.zshrc`를 실행하여 적용하거나, 터미널을 재시작하세요.

    **설정 확인**

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

    API Key가 출력되면 설정이 완료된 것입니다.
  </Tab>
</Tabs>

## Step 3: Codex CLI 사용 시작

### 1. 작업 디렉토리로 이동

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

**참고:** `your-working-directory`를 실제 경로로 교체하세요

### 2. 대화형 모드

```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. 설정 확인

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

**성공 표시:**

* AI 응답 텍스트가 표시됩니다 (여러 줄)
* `401`, `403`, `API Key invalid` 등의 오류가 **없어야** 합니다

**오류가 표시되는 경우:**

* `401 Unauthorized`: API Key가 설정되지 않았거나 유효하지 않음 → 환경 변수를 확인하세요
* `403 Forbidden`: API Key 권한 부족 → API Key를 확인하세요
* `Network error`: 네트워크 문제 → 연결 상태를 확인하세요

## FAQ

### 1. Codex CLI란 무엇이며 어떤 용도로 사용하나요?

Codex CLI는 코드 관련 작업에 특화된 OpenAI의 공식 커맨드라인 도구입니다. 더 명확하고 실행 가능한 코드 변경 사항을 제공하는 엔지니어링 수준의 출력에 중점을 둡니다.

### 2. 처음 사용 시 설치 및 설정을 어떻게 확인하나요?

다음 명령어를 순서대로 실행하세요:

* `node -v` 및 `npm -v`: Node.js와 npm이 설치되었는지 확인
* `codex --version`: Codex CLI가 설치되었는지 확인
* `codex "Who are you"`: API 설정이 올바른지 확인

### 3. 대화형 모드와 단일 명령어 모드의 차이점은 무엇인가요?

* **대화형 모드**: `codex`를 실행하여 다중 턴 대화를 위한 연속 대화에 진입합니다
* **단일 명령어 모드**: `codex "질문"`을 실행하여 단일 응답을 받고 종료합니다

### 4. Codex CLI가 자동으로 로컬 파일과 코드를 읽거나 업로드하나요?

아니요. Codex CLI는 사용자가 명시적으로 참조하거나 승인한 경우에만 파일 내용을 읽습니다. 전용 프로젝트 폴더에서 사용하는 것을 권장합니다.

### 5. Codex CLI로 로컬 파일 내용을 분석하려면 어떻게 하나요?

대화형 모드에서 다음 방법으로 파일을 참조할 수 있습니다:

* 파일 경로를 입력하여 Codex가 읽도록 합니다
* 파일을 터미널 창으로 드래그합니다
* 파일 내용을 복사하여 붙여넣습니다

### 6. Codex CLI는 한국어 입출력을 지원하나요?

네, 완벽하게 지원합니다.

### 7. 실행 후 출력이 없는 경우 원인은 무엇인가요?

일반적인 원인:

* 네트워크 연결 문제
* 유효하지 않은 API Key 또는 잔액 부족
* 잘못된 `base_url` 설정
* 방화벽 또는 프록시가 요청을 차단

### 8. 설정 변경이 적용되지 않는 이유는 무엇인가요?

* 터미널을 재시작하세요
* `config.toml` 구문을 확인하세요 (TOML 형식)
* 설정 파일 경로를 확인하세요:
  * Windows: `C:\Users\{username}\.codex\config.toml`
  * macOS / Linux: `~/.codex/config.toml`

### 9. 401/403 오류의 원인은 무엇인가요?

* **401 오류**: `OPENAI_API_KEY`가 설정되지 않았거나 유효하지 않음
* **403 오류**: 권한 부족 또는 만료된 키
* `env_key`가 환경 변수 이름과 일치하는지 확인하세요

### 10. Codex CLI는 어떤 시나리오에 적합한가요?

**적합한 경우:**

* 코드 작성, 디버깅 및 리팩토링
* 커맨드라인 환경에서의 빠른 Q\&A
* 파일 내용 분석

**적합하지 않은 경우:**

* 복잡한 GUI 상호작용
* 실시간 협업 편집

### 11. 모델을 변경하려면 어떻게 하나요?

설정 파일 `config.toml` (`~/.codex/config.toml` 또는 `C:\Users\{username}\.codex\config.toml`에 위치)을 열고, `model` 필드를 수정하세요:

```toml theme={null}
model = "gpt-5.2"  # 원하는 모델 이름으로 변경
```

파일을 저장하고 Codex CLI를 재시작하면 변경 사항이 적용됩니다.

### 12. 이미지를 업로드하려면 어떻게 하나요?

* 방법 1: 이미지 경로를 참조
* 방법 2: 이미지를 터미널로 드래그 앤 드롭
* 방법 3: 이미지를 직접 붙여넣기

모든 방법은 사용자의 조작이 필요합니다. Codex CLI는 자동으로 로컬 이미지를 읽거나 업로드하지 않습니다.

### 13. 커맨드라인 터미널 여는 방법

<Tabs>
  <Tab title="Windows">
    * 방법 1: `Win + R`을 누르고, `cmd` 또는 `powershell`을 입력한 후 Enter를 누르세요
    * 방법 2: 시작 메뉴에서 "명령 프롬프트" 또는 "PowerShell"을 검색하세요
    * 방법 3: 폴더에서 Shift를 누른 채 마우스 오른쪽 버튼을 클릭하고 "여기에 PowerShell 창 열기"를 선택하세요
  </Tab>

  <Tab title="macOS">
    * 방법 1: `Command + Space`를 눌러 Spotlight를 열고, `Terminal`을 입력한 후 Enter를 누르세요
    * 방법 2: "응용 프로그램" → "유틸리티" → "터미널"로 이동하세요
  </Tab>

  <Tab title="Linux">
    * 방법 1: `Ctrl + Alt + T` 단축키를 누르세요
    * 방법 2: 애플리케이션 메뉴에서 "Terminal"을 검색하세요
  </Tab>
</Tabs>

## 주의사항

<Warning>
  Codex CLI는 전용 프로젝트 폴더에서 실행하세요. 민감한 디렉토리(시스템 폴더 또는 자격 증명이 포함된 디렉토리 등)에서는 실행하지 마세요. Codex CLI는 현재 작업 디렉토리를 기준으로 작동합니다.
</Warning>

<Tip>
  설정의 `wire_api`는 반드시 `"responses"`로 설정해야 합니다. `"chat"`은 더 이상 사용되지 않습니다.
</Tip>