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

# Codex CLI 터미널 사용 가이드

> Codex 集成指南 - Ace Data Cloud

Codex CLI는 OpenAI에서 출시한 오픈 소스 로컬 프로그래밍 에이전트로, 터미널에서 실행됩니다. 코드를 읽고, 파일을 수정하며, 명령을 실행하고, 오류를 해석하며 일상적인 개발 작업을 돕습니다.

Codex CLI는 사용자 지정 모델 공급자를 지원하며, Ace Data Cloud가 제공하는 OpenAI Responses 호환 프록시를 통해 별도의 OpenAI 공식 계정 구독 없이 사용할 수 있습니다. 설정 완료 후 Codex CLI는 요청을 `https://api.acedata.cloud/v1`로 전송합니다.

## 신청 절차

Codex CLI를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API 토큰을 받아 두세요.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

로그인 또는 회원가입하지 않은 경우 자동으로 로그인 페이지로 이동하며, 로그인 후 현재 페이지로 자동 복귀합니다.

초기 신청 시 무료 할당량이 제공되어 Codex CLI 서비스를 무료로 체험할 수 있습니다.

## Codex CLI 설치

Codex CLI는 macOS, Linux, Windows, WSL을 지원합니다. npm을 통해 설치하거나 macOS에서는 Homebrew를 사용할 수 있습니다.

### npm 설치 (추천)

Node.js가 설치되어 있다면 npm으로 직접 설치할 수 있습니다. Node.js 18 이상 버전이 필요합니다.

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

### Homebrew 설치 (macOS)

macOS 사용자는 Homebrew로도 설치 가능합니다:

```bash theme={null}
brew install --cask codex
```

### 설치 확인

설치 후 터미널을 다시 열고 명령어가 작동하는지 확인하세요:

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

`command not found` 오류가 발생하면 현재 터미널에 새 PATH가 적용되지 않은 경우가 많습니다. 터미널을 닫았다가 다시 열거나 설치 스크립트 출력에 안내된 PATH 설정을 확인하세요.

## Codex CLI 설정

설치 후 Codex CLI는 기본적으로 OpenAI 공식 서비스에 연결을 시도합니다. Ace Data Cloud를 사용하려면 Codex 설정 파일에 사용자 지정 `model_provider`를 선언하고 API 토큰을 해당 환경 변수에 넣어야 합니다.

### 1단계: 환경 변수 설정

API 토큰을 Shell 설정 파일(`~/.zshrc`, `~/.bashrc`, `~/.bash_profile` 등)에 작성하는 것을 권장합니다:

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

여기서 `{token}`은 Ace Data Cloud 콘솔에서 복사한 API 토큰으로 교체하세요.

설정 후 터미널을 다시 열거나 다음 명령어로 즉시 적용할 수 있습니다:

```bash theme={null}
source ~/.zshrc
```

### 2단계: Codex 설정 파일 편집

Codex CLI는 `~/.codex/config.toml`을 전역 설정 파일로 사용합니다. 파일이 없으면 새로 만드세요:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

다음 내용을 `~/.codex/config.toml`에 작성하세요:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

각 필드 설명:

| 필드                                        | 설명                                                 |
| ----------------------------------------- | -------------------------------------------------- |
| `model_provider`                          | 기본 사용 공급자 이름, 아래 `[model_providers.<name>]` 키와 일치  |
| `model`                                   | 기본 사용 모델 ID                                        |
| `model_reasoning_effort`                  | 추론 강도, 일반 값: `low`, `medium`, `high`               |
| `[model_providers.acedatacloud].base_url` | Ace Data Cloud OpenAI Responses 프록시 주소             |
| `[model_providers.acedatacloud].env_key`  | Codex CLI가 API 토큰을 읽는 환경 변수 이름                     |
| `[model_providers.acedatacloud].wire_api` | 프로토콜 유형, OpenAI Responses API 사용 시 `responses`로 설정 |

### 이전 OpenAI 로그인 캐시 정리

이전에 OpenAI 공식 계정으로 Codex CLI에 로그인한 적이 있다면, 로컬에 공식 로그인 상태가 캐시되어 있을 수 있습니다(`~/.codex/auth.json`에 보통 저장됨). Ace Data Cloud 프록시로 전환하기 전에 이전 로그인을 정리하는 것이 좋습니다:

```bash theme={null}
codex logout
```

`codex logout` 명령이 없으면 수동으로 캐시 파일을 삭제할 수 있습니다:

```bash theme={null}
rm -f ~/.codex/auth.json
```

OpenAI 공식 계정으로 로그인한 적이 없다면 이 단계는 건너뛰세요.

### 세션 시작

프로젝트 디렉터리로 이동한 후 Codex CLI를 실행하세요:

```bash theme={null}
cd /path/to/your/project
codex
```

Codex 인터랙티브 화면이 나타나면 다음과 같이 명령을 입력할 수 있습니다:

```text theme={null}
이 프로젝트의 디렉터리 구조를 설명해줘
```

### 설정 확인

Codex CLI 진입 후 현재 모델과 공급자를 확인하려면:

```text theme={null}
/model
```

현재 모델이 `acedatacloud` 공급자에서 왔는지 확인할 수 있습니다:

```text theme={null}
Model: gpt-5
Provider: acedatacloud
```

공급자가 `acedatacloud`가 아니면 설정이 적용되지 않은 것입니다. `~/.codex/config.toml` 저장 여부와 현재 터미널에서 `ACEDATACLOUD_API_KEY`가 읽히는지 확인하세요:

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

또한 [Ace Data Cloud 콘솔 - 사용 내역](https://platform.acedata.cloud/console/usages)에서 요청 기록과 과금 내역을, [Ace Data Cloud 콘솔 - 애플리케이션 목록](https://platform.acedata.cloud/console/applications)에서 잔여 할당량을 확인할 수 있습니다.

## 작동 원리

Codex CLI는 기본적으로 OpenAI Responses API 프로토콜을 사용합니다. Ace Data Cloud는 `https://api.acedata.cloud/v1/responses`에서 OpenAI Responses API 호환 프록시 서비스를 제공하므로, Codex CLI는 별도의 로컬 프록시나 추가 플러그인이 필요 없습니다.

작동 과정:

1. Codex CLI가 `~/.codex/config.toml`에서 `model_provider`를 읽고 `[model_providers.acedatacloud]` 설정을 로드합니다.
2. `env_key`에 지정된 환경 변수(`ACEDATACLOUD_API_KEY`)에서 API 토큰을 읽습니다.
3. `wire_api = "responses"` 프로토콜을 통해 요청을 `base_url + /responses` 즉, `https://api.acedata.cloud/v1/responses`로 전송합니다.
4. Ace Data Cloud가 API 토큰으로 인증, 할당량 확인 후 요청을 적절한 상위 모델 채널로 전달합니다.
5. 요청 완료 후 실제 사용량에 따라 플랫폼이 사용량을 기록하고 할당량을 차감합니다.

즉, 기존 `codex` 명령과 Codex CLI의 기본 인터랙션 경험을 유지하면서, 하위 모델 서비스만 Ace Data Cloud로 전환하는 것입니다.

## 모델 설정

`~/.codex/config.toml`의 `model` 필드가 Codex 기본 모델을 결정합니다. Ace Data Cloud OpenAI Responses 서비스는 여러 모델을 지원하며, 주요 모델은 다음과 같습니다:

| 모델                 | 설명                       |
| ------------------ | ------------------------ |
| `gpt-5`            | 기본 추천 모델, 대부분 코딩 작업에 적합  |
| `gpt-5-mini`       | 경량화, 더 빠른 응답, 간단한 작업에 적합 |
| `gpt-5.5`          | 최신 버전, 성능 향상             |
| `gpt-5.5-pro`      | 강화 버전, 복잡한 추론 작업에 적합     |
| `gpt-4.1`          | 이전 세대 주력 모델              |
| `o3`               | 추론 강화 모델, 심층 추론 작업에 적합   |
| `o4-mini-high-all` | 경량 추론 모델                 |

임시로 모델을 바꾸려면 Codex 실행 시 명령행 인자를 사용할 수 있습니다:

```bash theme={null}
codex --model gpt-5-mini
```

또는 `~/.codex/config.toml`의 `model` 필드를 수정한 후 재시작하세요. 전체 모델 목록은 [Ace Data Cloud OpenAI 서비스 문서](https://platform.acedata.cloud/documents/openai)를 참고하세요.

## 프로젝트 신뢰 수준

Codex CLI는 프로젝트별로 신뢰 수준을 설정하여 에이전트가 수행할 작업을 제어할 수 있습니다. `~/.codex/config.toml` 파일 끝에 다음을 추가하세요:

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

설명:

* `trusted`: 에이전트가 전체 권한을 가지고 명령 실행, 파일 수정 가능
* `untrusted`: 제한된 권한만 부여, 익숙하지 않은 프로젝트에 적합

## 더 알아보기

* [Codex CLI 공식 저장소](https://github.com/openai/codex)
* [Ace Data Cloud OpenAI 서비스 문서](https://platform.acedata.cloud/documents/openai)
* [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)