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

# Codex

> Codex 연동 가이드: GravitexAI를 통해 터미널에서 GPT 전체 제품군 사용

## 1. 개요

**Codex**는 OpenAI의 공식 터미널 기반 코딩 에이전트로, 코드 생성, 코드 리뷰 및 복잡한 엔지니어링 작업을 위해 설계되었습니다. **GravitexAI**(OpenAI 호환)를 통해 다음을 사용할 수 있습니다:

<CardGroup cols={2}>
  <Card title="통합 액세스" icon="plug">
    하나의 API 키로 GPT-5.5 / 5.4 / 5.4-Pro 및 GPT 전체 제품군에 접근
  </Card>

  <Card title="Responses API" icon="bolt">
    최신 GPT 모델을 위한 내장 `wire_api = "responses"`
  </Card>

  <Card title="고가용성" icon="shield-check">
    자동 장애 조치 및 안정적인 글로벌 라우팅을 갖춘 분산 인프라
  </Card>

  <Card title="종량제" icon="wallet">
    구독 없이 토큰 기반 과금 — 공식 엔드포인트보다 더 나은 가성비
  </Card>
</CardGroup>

## 2. 사전 요구사항

* **Codex CLI** 설치 (Codex 공식 설치 안내를 따르세요)
* [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 생성한 **API 키** (형식 `sk-xxxxxxxxxx`)

<Tip>
  **Base URL**: `https://api.gravitex.ai/v1` — 반드시 `/v1`로 끝나야 합니다.
</Tip>

## 3. 빠른 설정

Codex는 TOML 설정으로 provider를 선언합니다. 커스텀 provider에 환경 변수가 불안정할 수 있으므로 **TOML에 설정을 직접 작성하는 것을 권장**합니다.

### `~/.codex/config.toml` 편집

<Steps>
  <Step title="설정 파일 열기">
    ```bash theme={null}
    # macOS / Linux
    nano ~/.codex/config.toml

    # Windows
    notepad %USERPROFILE%\.codex\config.toml
    ```
  </Step>

  <Step title="다음 내용 붙여넣기">
    ```toml theme={null}
    model = "gpt-5.5"
    model_provider = "openai-custom"
    personality = "pragmatic"
    model_reasoning_effort = "high"

    [model_providers.openai-custom]
    name = "GravitexAI"
    base_url = "https://api.gravitex.ai/v1"
    wire_api = "responses"

    # Custom providers usually need the key injected explicitly:
    [model_providers.openai-custom.http_headers]
    Authorization = "Bearer YOUR_API_KEY"
    Content-Type = "application/json"
    ```
  </Step>

  <Step title="Codex 실행">
    ```bash theme={null}
    cd your-project-folder
    codex
    ```

    Codex는 이 설정을 기반으로 GravitexAI가 제공하는 GPT 모델을 사용합니다.
  </Step>
</Steps>

## 4. 추천 모델 (GravitexAI 경유)

Codex는 현재 GPT 제품군 모델 ID를 지원합니다. GravitexAI에서 가장 많이 사용되는 조합:

| 모델 ID             | 최적 용도           | 참고                          |
| ----------------- | --------------- | --------------------------- |
| **gpt-5.5** ⭐     | 복잡한 추론, 프로덕션 코드 | OpenAI 최신 플래그십              |
| **gpt-5.4**       | 일반 채팅, 코드 생성    | 프로 작업을 위한 차세대 메인 모델         |
| **gpt-5.4-pro**   | 대규모 리팩터링 / 추론   | 고성능 변형                      |
| **gpt-5.4-mini**  | 비용과 속도 균형       | 일상 개발                       |
| **gpt-5.4-nano**  | 고동시성 / 저비용      | 경량 워크로드                     |
| **gpt-5.1-codex** | 코드 중심 완성        | `wire_api = "responses"` 필요 |

<Tip>
  Codex는 GPT 제품군 ID만 지원합니다 (예: `gpt-5.5`, `gpt-5.4`, `gpt-5.1-codex`). 전체 목록은 [GravitexAI 모델 카탈로그](https://maas.gravitex.ai/#/models)를 참조하세요.
</Tip>

## 5. Personality 및 Reasoning

Codex는 동작을 사용자 지정하기 위한 두 가지 선택적 설정을 제공합니다: **personality**와 **model\_reasoning\_effort**.

### 5.1 Personality

응답의 **어조와 스타일**을 제어합니다.

```toml theme={null}
personality = "pragmatic"
```

| 옵션           | 설명                 |
| ------------ | ------------------ |
| `pragmatic`  | 직접적이고 실용적, 최소한의 설명 |
| `concise`    | 짧고 핵심만             |
| `detailed`   | 더 많은 맥락과 설명        |
| `analytical` | 구조적, 논리 중심         |
| `creative`   | 표현력 있고 유연함         |

<Tip>
  Personality는 **소프트 선호**이며 엄격히 강제되지 않습니다. 정밀한 제어가 필요하면 system prompt를 사용하세요.
</Tip>

### 5.2 Reasoning effort

모델이 "사고"에 사용하는 정도를 제어합니다 — OpenAI Responses API의 `reasoning.effort` 필드에 매핑됩니다.

```toml theme={null}
model_reasoning_effort = "high"
```

| 옵션       | 설명       | 최적 용도             |
| -------- | -------- | ----------------- |
| `low`    | 가장 빠른 응답 | 빠른 Q\&A, 문구 생성    |
| `medium` | 속도/품질 균형 | 일상 코딩             |
| `high`   | 심층 추론    | 복잡한 디버깅, 설계, 알고리즘 |

<Tip>
  Reasoning effort가 높을수록 시간과 토큰이 더 소모되지만, 어려운 코딩 및 디버깅 작업의 품질이 크게 향상됩니다.
</Tip>

### 5.3 전체 예시

```toml theme={null}
model = "gpt-5.5"
model_provider = "openai-custom"
personality = "pragmatic"
model_reasoning_effort = "high"

[model_providers.openai-custom]
name = "GravitexAI"
base_url = "https://api.gravitex.ai/v1"
wire_api = "responses"

[model_providers.openai-custom.http_headers]
Authorization = "Bearer sk-your-gravitex-key"
Content-Type = "application/json"
```

이 설정으로 다음을 얻을 수 있습니다:

* 명확하고 실용적인 답변
* 복잡한 작업을 위한 심층 추론
* Responses API를 통한 GPT-5.5 전체 기능

## 6. FAQ

<AccordionGroup>
  <Accordion title="401 / invalid API key">
    1. [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 키를 다시 확인하세요 — 공백이나 줄바꿈에 주의하세요.
    2. `Authorization` 헤더가 `Bearer sk-xxxxxxxxxx`인지 확인하세요.
    3. 잔액이 양수인지 확인하세요.
  </Accordion>

  <Accordion title="404 / wrong endpoint">
    Base URL이 **반드시 `/v1`로 끝나는지** 확인하세요:

    ```toml theme={null}
    base_url = "https://api.gravitex.ai/v1"
    ```

    흔한 실수: `/v1` 누락, `/responses` 추가, `http://` 대신 `https://` 사용.
  </Accordion>

  <Accordion title="Model not found">
    1. 모델 ID가 [GravitexAI 모델 목록](https://maas.gravitex.ai/#/models)에 있는지 확인하세요.
    2. Codex는 GPT 제품군 ID만 지원합니다 (Claude / Gemini 불가).
    3. 모델 이름은 대소문자를 구분합니다.
  </Accordion>

  <Accordion title="gpt-5.1-codex에서 chatCompletion 오류">
    `gpt-5.1-codex` / `gpt-5.2-codex` 및 유사 Codex 모델은 **Responses API만 지원**합니다. provider 설정에 다음이 있는지 확인하세요:

    ```toml theme={null}
    [model_providers.openai-custom]
    wire_api = "responses"
    ```
  </Accordion>

  <Accordion title="환경 변수가 작동하지 않나요?">
    커스텀 provider의 경우 Codex가 `OPENAI_API_KEY`를 자동 주입하지 않을 수 있습니다. **권장**: `http_headers`를 통해 `Authorization`을 명시적으로 설정하세요:

    ```toml theme={null}
    [model_providers.openai-custom.http_headers]
    Authorization = "Bearer sk-your-key"
    ```
  </Accordion>
</AccordionGroup>

## 7. 참고 자료

* GravitexAI 콘솔: [https://maas.gravitex.ai](https://maas.gravitex.ai)
* 모델 카탈로그: [https://maas.gravitex.ai/#/models](https://maas.gravitex.ai/#/models)
* API 키: [https://maas.gravitex.ai/#/keys](https://maas.gravitex.ai/#/keys)
* OpenAI Responses API: [https://platform.openai.com/docs/api-reference/responses](https://platform.openai.com/docs/api-reference/responses)