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

# VS Code용 Codex 사용 가이드

> Codex 集成指南 - Ace Data Cloud

Codex는 OpenAI에서 출시한 프로그래밍 에이전트입니다. 터미널 CLI 외에도 VS Code 확장으로 제공되어, 편집기 사이드바에서 채팅하고, 파일을 읽고, 컨텍스트를 참조하며, 코드를 생성·수정하고 변경사항을 미리 볼 수 있습니다.

이 문서에서는 Ace Data Cloud의 OpenAI Responses 호환 프록시를 통해 VS Code에서 Codex 확장을 설정하고 사용하는 방법을 소개합니다. Codex VS Code 확장과 Codex CLI는 동일한 로컬 구성 체계를 사용하므로, `~/.codex/config.toml`을 Ace Data Cloud로 지정하면 VS Code 내 Codex가 `https://api.acedata.cloud/v1` 경로를 사용하게 됩니다.

## 신청 절차

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

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

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

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

## Codex 확장 설치

VS Code 확장 마켓플레이스에서 `Codex`를 검색하여 OpenAI가 배포한 **Codex - OpenAI's coding agent** 확장을 설치하세요. 마켓플레이스 ID는 다음과 같습니다:

```text theme={null}
openai.chatgpt
```

명령줄에서도 설치할 수 있습니다:

```bash theme={null}
code --install-extension openai.chatgpt
```

설치 후 VS Code를 재시작하거나 다시 로드하세요. Codex 메뉴가 보이지 않으면 명령 팔레트(macOS: `Cmd+Shift+P`, Windows/Linux: `Ctrl+Shift+P`)를 열고 다음을 검색하여 실행하세요:

```text theme={null}
Codex: Open Codex Sidebar
```

Codex는 기본적으로 VS Code 우측 사이드바에 나타납니다. 필요에 따라 왼쪽 Activity Bar로 드래그할 수도 있습니다.

## Codex CLI 설치 (검증용)

공식 문서에 따르면 Codex VS Code 확장과 Codex CLI는 동일한 구성 계층을 사용합니다. VS Code 설정 전에 API 토큰과 모델 사용 가능 여부를 검증하려면 Codex CLI 설치를 권장합니다.

공식 권장 방법 중 하나는 npm을 통한 설치이며, Node.js 18 이상이 필요합니다:

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

macOS 사용자는 Homebrew로도 설치할 수 있습니다:

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

설치 후 터미널에서 명령어가 정상 작동하는지 확인하세요:

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

VS Code 확장만 사용할 경우 CLI 검증 단계를 건너뛸 수 있으며, 이후에도 동일한 `~/.codex/config.toml` 구성을 사용합니다.

## Ace Data Cloud API 구성

Codex VS Code 확장과 CLI는 구성 파일을 공유합니다. 기본적으로 Codex는 OpenAI 공식 계정 로그인 또는 공식 API 키 구성을 요구합니다. Ace Data Cloud를 사용하려면 API 토큰과 `~/.codex/config.toml`을 설정해야 합니다.

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

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

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

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

설정 후 터미널을 다시 열거나 다음 명령어로 즉시 적용하세요:

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

VS Code가 이미 열려 있다면 재시작하거나 다시 로드하여 확장이 새 환경 변수를 인식하도록 합니다.

### 2단계: Codex 구성 파일 편집

Codex 사용자 구성 파일은 `~/.codex/config.toml`에 위치합니다. 파일이 없으면 새로 만드세요:

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

다음 내용을 작성합니다:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[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.acedatacloud]`와 연결 |
| `model`                  | 기본 모델 ID                                           |
| `model_reasoning_effort` | 추론 강도, 일반적으로 `low`, `medium`, `high` 사용            |
| `approval_policy`        | 명령 실행 전 확인 정책, 일상 사용 시 `on-request` 권장             |
| `sandbox_mode`           | Codex 명령 실행 시 샌드박스 권한, 일상 개발은 `workspace-write` 권장 |
| `base_url`               | Ace Data Cloud OpenAI 호환 API 주소                    |
| `env_key`                | Codex가 API 토큰을 읽는 환경 변수 이름                         |
| `wire_api`               | 프로토콜 유형, OpenAI Responses API 사용 시 `responses`로 설정 |

또한 Codex 확장 우측 상단 톱니바퀴 아이콘을 클릭해 **Codex Settings > Open config.toml**을 선택하면 VS Code 내에서 직접 이 구성 파일을 열 수 있습니다.

### 프로젝트별 구성

특정 프로젝트에 별도 구성을 적용하려면 프로젝트 루트에 `.codex/config.toml`을 생성하세요. Codex는 프로젝트가 신뢰(trusted) 상태일 때만 프로젝트별 구성을 우선적으로 로드합니다.

예시:

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

개인 토큰이 포함된 구성은 환경 변수로 관리하고, 프로젝트 저장소에는 포함하지 않는 것을 권장합니다. 프로젝트별 `.codex/config.toml` 파일도 팀 정책에 따라 제출 여부를 결정하세요.

## 기존 OpenAI 로그인 캐시 정리

이전에 Codex 확장에서 OpenAI 공식 계정으로 로그인한 적이 있다면 로컬에 로그인 상태가 남아 있을 수 있습니다. Ace Data Cloud 프록시로 전환하기 전에 터미널에서 다음 명령어를 실행하세요:

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

명령어가 없으면 로컬 캐시 파일을 삭제할 수도 있습니다:

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

그 후 VS Code를 재시작하거나 다시 로드하세요.

## 기본 사용법

구성이 완료되면 VS Code 좌측 또는 우측의 Codex 패널을 열고 요구사항을 입력하세요. 예:

```text theme={null}
현재 프로젝트의 디렉터리 구조를 설명하고 주요 진입 파일을 알려주세요.
```

Codex 확장은 편집기 내 파일과 선택한 코드를 컨텍스트로 활용할 수 있습니다. 입력창에서 `@`를 사용해 파일을 참조할 수도 있습니다. 예:

```text theme={null}
@src/App.vue를 참고하여 이 페이지를 더 명확한 컴포넌트로 분리해주세요.
```

코드 일부를 선택한 상태에서 명령 팔레트를 열고 다음을 실행할 수 있습니다:

```text theme={null}
Codex: Add to Codex Thread
```

또는 현재 파일 전체를 컨텍스트에 추가하려면:

```text theme={null}
Codex: Add File to Codex Thread
```

를 실행하세요.

## 모델 및 추론 강도 변경

Codex VS Code 확장에서는 입력창 아래 모델 선택기에서 모델을 전환하고 reasoning effort를 조절할 수 있습니다. Ace Data Cloud 커스텀 공급자 사용 시 가장 안정적인 방법은 `~/.codex/config.toml`에 기본 `model`을 설정한 뒤 필요에 따라 UI에서 변경하는 것입니다. 기본 권장 설정은 다음과 같습니다:

| 상황                | 권장 모델                      | 추론 강도    |
| ----------------- | -------------------------- | -------- |
| 일상 코드 읽기 및 소규모 수정 | `gpt-5-mini`               | `medium` |
| 일반 개발 작업          | `gpt-5`                    | `high`   |
| 복잡한 리팩토링 및 심층 추론  | `gpt-5.5` 또는 `gpt-5.5-pro` | `high`   |
| 추론 강화 작업          | `o3`                       | `high`   |

원하는 모델이 UI에 없으면 `~/.codex/config.toml`의 `model` 필드를 직접 수정하고 VS Code를 재시작하거나 다시 로드하세요. 전체 모델 목록은 [Ace Data Cloud OpenAI 서비스 문서](https://platform.acedata.cloud/documents/openai)를 참고하세요.

## 작업 모드 선택

Codex 확장은 여러 작업 모드를 지원합니다. 주요 모드는 다음과 같습니다:

| 모드                    | 적용 상황                                                |
| --------------------- | ---------------------------------------------------- |
| `Chat`                | 코드 토론, 설명, 계획 수립만 원하며 Codex가 직접 파일을 수정하지 않길 원할 때     |
| `Agent`               | Codex가 파일을 읽고 코드 수정 및 필요한 명령 실행을 하도록 하는 일상 개발용 권장 모드 |
| `Agent (Full Access)` | 더 높은 권한과 네트워크 접근을 허용, 위험을 명확히 인지한 상황에 적합             |

일상적으로는 `Agent` 모드를 사용하고 `approval_policy = "on-request"`를 유지하는 것이 좋습니다. 이렇게 하면 Codex가 민감한 명령 실행, 작업 공간 외부 경로 접근 또는 네트워크 사용 시 먼저 확인을 요청합니다.

## 구성 검증

터미널에서 동일한 구성을 사용해 Codex가 Ace Data Cloud를 통해 정상 작동하는지 확인할 수 있습니다:

```bash theme={null}
codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"
```

구성이 올바르면 다음과 같은 응답을 받게 됩니다:

```text theme={null}
ADC_Codex_OK
```

이후 VS Code에서 Codex 패널을 열고 간단한 질문을 입력해 보세요:

```text theme={null}
현재 작업 공간의 용도를 한 문장으로 설명해주세요.
```

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

## 작동 원리

Codex VS Code 확장은 독립적인 모델 구성을 갖지 않습니다. 로컬 Codex CLI를 사용하며 구성 계층을 공유합니다:

1. VS Code 확장이 Codex를 시작하고 사용자 `~/.codex/config.toml`을 읽음
2. 현재 프로젝트가 신뢰되고 `.codex/config.toml`이 존재하면 프로젝트별 구성도 로드
3. `model_provider`가 `acedatacloud`일 경우 `ACEDATACLOUD_API_KEY`에서 API 토큰을 읽음
4. 요청은 OpenAI Responses 프로토콜을 통해 `https://api.acedata.cloud/v1/responses`로 전송됨
5. Ace Data Cloud가 인증, 할당량 확인, 요청 전달 및 사용량 기록 수행

따라서 터미널 CLI와 VS Code 확장은 보통 한 번만 구성하면 됩니다. 터미널에서 검증이 완료되면 VS Code 확장도 동일한 구성을 사용합니다.

## 추가 정보

* [Codex IDE extension 공식 문서](https://developers.openai.com/codex/ide)
* [Codex IDE extension 설정 참고](https://developers.openai.com/codex/ide/settings)
* [Codex CLI 기본 구성](https://developers.openai.com/codex/config-basic)
* [Ace Data Cloud OpenAI 서비스 문서](https://platform.acedata.cloud/documents/openai)