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

# Codex CLI에서 APIMart 사용하기

> Codex CLI에서 APIMart API 서비스를 설정하고 사용하는 방법을 자세히 안내합니다. 간단한 설정만으로 Codex CLI에서 다양한 AI 모델을 호출하여 프로그래밍을 지원합니다.

## 소개

Codex CLI는 OpenAI가 공개한 오픈 소스 터미널 코딩 에이전트로, 커맨드라인에서 직접 파일을 읽고 쓰고 명령을 실행하며 버그를 수정하고 코딩 작업을 완수할 수 있습니다.
APIMart에 연결하면 GPT, Claude를 비롯한 다양한 모델을 Codex CLI에서 자유롭게 사용할 수 있으며, 더 유연하고 합리적인 요금 체계의 혜택도 누릴 수 있습니다.

## 준비 사항

시작하기 전에 다음을 확인하세요:

1. **Node.js 설치 완료**
   [Node.js 공식 사이트](https://nodejs.org/)에서 다운로드하여 설치하세요 (최신 LTS, v20 이상 권장). npm으로 Codex CLI를 설치하기 위해 필요합니다

2. **APIMart API 키 획득 완료**
   [APIMart 콘솔](https://apimart.ai/keys)에 로그인하여 API 키를 받으세요 (`sk-`로 시작)

<Note>**팁:** APIMart 계정이 없으시다면 먼저 [APIMart](https://apimart.ai)에서 가입하고 API 키를 받으세요.</Note>

## 1단계: Codex CLI 설치

다음 방법 중 하나를 선택해 설치하세요:

<Tabs>
  <Tab title="npm (권장)">
    npm으로 전역 설치합니다. 모든 운영체제에 적용됩니다:

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

    <Note>권한 문제가 발생하면 명령 앞에 `sudo`를 붙이세요 (macOS / Linux).</Note>
  </Tab>

  <Tab title="Homebrew (macOS)">
    macOS 사용자는 Homebrew로도 설치할 수 있습니다:

    ```bash theme={null}
    brew install codex
    ```
  </Tab>
</Tabs>

### 설치 확인

설치 후 다음 명령으로 정상 설치 여부를 확인합니다:

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

버전 번호가 출력되면 설치 성공입니다.

## 2단계: APIMart API 설정

Codex CLI는 `~/.codex/` 디렉터리의 설정 파일로 모델 공급자를 관리합니다. APIMart를 가리키는 커스텀 공급자 하나만 추가하면 됩니다.

### 2.1 설정 디렉터리 위치

* **macOS / Linux:** `~/.codex/`
* **Windows:** `C:\Users\<사용자명>\.codex\`

<Note>디렉터리가 없다면 터미널에서 `codex`를 한 번 실행한 뒤 `Ctrl + C`로 종료하세요. 자동으로 생성됩니다.</Note>

### 2.2 API 키 설정

설정 디렉터리에 `auth.json` 파일을 만들거나 열어 APIMart 키를 입력합니다:

```json theme={null}
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxx"
}
```

| 필드               | 설명                            |
| ---------------- | ----------------------------- |
| `OPENAI_API_KEY` | 본인의 APIMart API 키 (`sk-`로 시작) |

### 2.3 모델 공급자 설정

설정 디렉터리에 `config.toml` 파일을 만들거나 열어 APIMart 공급자를 추가합니다:

```toml theme={null}
# 기본 사용 모델
model = "gpt-5.5"
# 기본 공급자 — 아래 [model_providers.apimart]와 매칭
model_provider = "apimart"

# APIMart 공급자 설정
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

| 필드                     | 설명                                                     |
| ---------------------- | ------------------------------------------------------ |
| `model`                | 기본 모델 ID. 아래 모델 목록에서 선택                                |
| `model_provider`       | 기본 공급자. `[model_providers.xxx]`의 ID와 일치해야 함            |
| `name`                 | 공급자 표시 이름. 자유롭게 지정 가능                                  |
| `base_url`             | APIMart의 OpenAI 호환 주소. `https://api.apimart.ai/v1`로 고정 |
| `wire_api`             | 통신 프로토콜. 최신 Codex는 `responses` (Responses API) 사용 필요   |
| `requires_openai_auth` | `true`로 설정하면 `auth.json`의 키로 인증합니다                     |

두 파일을 저장한 뒤 Codex CLI를 재시작하면 적용됩니다.

<Warning>`auth.json`은 올바른 JSON 형식, `config.toml`은 올바른 TOML 형식이어야 합니다. 전각 따옴표를 사용하지 마세요. 그러지 않으면 설정이 적용되지 않습니다.</Warning>

## 3단계: 시작하기

### 설정 확인

임의의 프로젝트 디렉터리에서 다음 명령을 실행해 설정이 올바른지 확인합니다:

```bash theme={null}
codex "한 문장으로 자신을 소개해 주세요"
```

AI 응답이 오면 설정 성공입니다. 로그인 화면이 뜨거나 `401`, `403` 오류가 발생하면 아래 자주 묻는 질문을 참고하세요.

### 대화형 모드

`codex`를 그대로 실행하면 대화형 UI로 진입합니다. 본격적인 코딩 작업에 적합합니다:

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

진입한 뒤 자연어로 요구사항을 설명하세요. 예시:

```
JSON을 반환하는 헬스 체크 엔드포인트를 포함한 Express.js 서버를 만들어 줘
```

Codex가 프로젝트를 분석해 코드를 생성하고, 명령을 실행하며, 민감한 작업 전에는 확인을 요청합니다.

### 승인 모드

처음 실행 시 Codex가 작업 승인 수준을 선택하라고 합니다:

| 모드        | 설명                                     |
| --------- | -------------------------------------- |
| **읽기 전용** | 파일 읽기만 허용. 모든 수정과 명령은 확인 필요            |
| **자동**    | 작업 디렉터리 내에서 파일 읽기/쓰기와 명령 실행 자율 수행 (권장) |
| **전체 접근** | 확인 없이 모든 작업 수행. 신중히 사용                 |

처음에는 **자동** 모드부터 시작하기를 권장합니다. 대화형 UI에서 `/approvals`를 입력하면 언제든 변경할 수 있습니다.

### 모델 전환

대화형 UI에서 `/model` 명령으로 빠르게 전환하거나, `config.toml`의 `model` 필드를 수정한 뒤 재시작하세요.

## 지원 모델

Codex CLI에서는 다음 GPT-5 시리즈 모델을 권장합니다:

| 모델 ID           | 특징                 | 추천 시나리오                 |
| --------------- | ------------------ | ----------------------- |
| `gpt-5.5`       | 최신 플래그십, 코딩 능력 최상  | Codex 1순위, 복잡한 엔지니어링 작업 |
| `gpt-5.4`       | 이전 세대 플래그십, 강력한 성능 | 복잡한 코딩, 아키텍처 설계         |
| `gpt-5.4-mini`  | 경량 버전, 빠르고 가성비 좋음  | 일상 코딩, 빠른 반복            |
| `gpt-5.3-codex` | Codex에 최적화된 코딩 모델  | 에이전트형 코딩 작업             |
| `gpt-5.2`       | 안정적이고 균형 잡힌 성능     | 일반 코딩 작업                |

<Tip>
  **모델 선택 가이드:** 위의 GPT-5 시리즈가 Codex CLI와 가장 잘 맞습니다. 최고의 경험을 원한다면 `gpt-5.5`를 우선 고려하세요. `gpt-5.3-codex`는 Codex의 에이전트형 코딩 시나리오에 특화되어 있습니다.
</Tip>

## 자주 쓰는 명령

Codex CLI에서 자주 쓰는 명령과 단축키:

| 명령                      | 설명                 |
| ----------------------- | ------------------ |
| `codex`                 | 대화형 UI 실행          |
| `codex "작업 내용"`         | 초기 명령과 함께 시작       |
| `codex exec "작업 내용"`    | 비대화 모드. 실행 후 즉시 종료 |
| `codex --model gpt-5.4` | 지정한 모델로 시작         |
| `codex --version`       | 버전 번호 확인           |
| `/model`                | 대화형 UI에서 모델 전환     |
| `/approvals`            | 대화형 UI에서 승인 모드 조정  |
| `Ctrl + C`              | 대화형 UI 종료          |

## 자주 묻는 질문

### Q1: 실행 후 ChatGPT 로그인 화면이 떠요?

실행 후 "Sign in with ChatGPT" 같은 로그인 안내가 보인다면 설정이 적용되지 않은 것입니다.

**점검 절차:**

1. `config.toml`과 `auth.json`이 모두 `~/.codex/` 안에 있는지 확인
2. `config.toml`의 `model_provider`가 `apimart`로 설정되어 있는지 확인
3. `auth.json`의 JSON 형식이 정확하고 키가 완전히 입력되었는지 확인

### Q2: 401 / 403 오류가 발생해요?

| 상태 코드              | 의미            | 해결 방법                                   |
| ------------------ | ------------- | --------------------------------------- |
| `401 Unauthorized` | API 키가 없거나 무효 | `auth.json`의 키가 올바르고 `sk-`로 시작하는지 확인    |
| `403 Forbidden`    | 권한 부족 또는 키 만료 | [콘솔](https://apimart.ai/keys)에서 키 상태 확인 |

또한 `base_url`이 `https://api.apimart.ai/v1`로 설정되어 있는지, OpenAI 공식 URL이 아닌지 확인하세요.

### Q3: 연결이 실패해요?

1. 네트워크 연결 상태 확인
2. `config.toml`의 `base_url` 설정이 올바른지 확인
3. 프록시를 사용 중이라면 `api.apimart.ai` 접근이 허용되어 있는지 확인

### Q4: `wire_api = "chat"`이 더 이상 지원되지 않는다고 떠요?

최신 Codex CLI (0.84.0 이상)에서는 `chat` 프로토콜이 제거되었습니다. `config.toml`의 `wire_api`를 `responses`로 변경하세요:

```toml theme={null}
wire_api = "responses"
```

APIMart는 이미 Responses API를 제공하므로, 수정 후 Codex를 재시작하기만 하면 됩니다.

### Q5: 도구 호출이나 실행이 실패해요?

`config.toml`의 `wire_api`가 `responses`로 설정되어 있는지 확인하세요. 호환성 이슈를 만나면 추천 GPT-5 시리즈 모델(예: `gpt-5.5`, `gpt-5.3-codex`)로 전환하는 것을 권장합니다. Codex CLI와의 궁합이 더 안정적입니다.

### Q6: auth.json 대신 환경 변수를 쓰고 싶어요?

환경 변수로도 키를 설정할 수 있습니다. `config.toml`의 공급자 설정을 다음과 같이 바꾸세요:

```toml theme={null}
[model_providers.apimart]
name = "APIMart"
base_url = "https://api.apimart.ai/v1"
wire_api = "responses"
env_key = "APIMART_API_KEY"
```

그리고 환경 변수 `APIMART_API_KEY`를 APIMart 키로 설정하면 됩니다. 이 경우 `auth.json`은 필요 없습니다.

### Q7: 모델은 어떻게 전환하나요?

두 가지 방법이 있습니다:

1. **대화형 UI에서**: `/model` 명령으로 전환
2. **설정 수정**: `config.toml`의 `model` 필드를 변경한 후 Codex CLI 재시작

### Q8: 사용량과 비용은 어떻게 확인하나요?

[APIMart 콘솔](https://apimart.ai/overview)에 로그인하여 API 호출 통계, 토큰 소비 내역, 비용 추이를 확인하세요.

## 지원

사용 중 문제가 발생하면:

* 📚 [APIMart 문서 센터](https://docs.apimart.ai)
* 💬 [Discord 커뮤니티](https://discord.gg/V8zqssyZ5c)
* 🐦 [Twitter @APIMart\_](https://x.com/APIMart_)
* 📧 기술 지원: [zhihong@apimart.ai](mailto:zhihong@apimart.ai)

***

<Card title="APIMart 시작하기" icon="rocket" href="https://apimart.ai">
  지금 바로 APIMart에 가입하고 API 키를 받아, Codex CLI에서 다중 모델 프로그래밍 어시스턴트를 경험해 보세요!
</Card>