# Codex

Codex는 Responses API로 모델과 통신합니다. config.toml에 NezhaGate를 가리키는 공급자를 추가하면 NezhaGate의 GPT 모델로 코드를 작성할 수 있습니다.

> https://nezhagate.com/ko/docs/integrations/codex

작성 기준 버전: Codex CLI 0.160

## 시작하기 전에

- Codex CLI를 설치하거나 VS Code, Cursor, Windsurf에 Codex 확장을 설치하고, 콘솔에서 API 키를 만드세요.

- Codex는 OpenAI Responses API(`/v1/responses`)만 사용하며, NezhaGate는 이 엔드포인트에서 GPT 모델을 제공합니다. Claude, Gemini와 그 밖의 모델은 채팅 엔드포인트나 [Claude Code](https://nezhagate.com/ko/docs/integrations/claude-code) 같은 도구를 쓰세요.

Codex에서 쓸 수 있는 모델:

`gpt-5.6-sol` · `gpt-5.6-terra` · `gpt-5.6-luna` · `gpt-5.5` · `gpt-6-astra` · `gpt-6.1-sol` · `gpt-6-sol` · `gpt-6-luna`

## config.toml에 공급자 추가하기

`~/.codex/config.toml`(Windows는 `%USERPROFILE%\.codex\config.toml`)을 열고, 없으면 새로 만든 뒤 아래 내용을 추가하세요:

```
model = "gpt-6.1-sol"
model_provider = "nezhagate"
web_search = "disabled"

[model_providers.nezhagate]
name = "NezhaGate"
base_url = "https://nezhagate.com/v1"
wire_api = "responses"
env_key = "NEZHAGATE_API_KEY"
```

- `model`, `model_provider` 같은 최상위 키는 첫 번째 `[...]` 섹션보다 앞에 와야 합니다. 그렇지 않으면 Codex가 이를 그 섹션의 내용으로 읽습니다.

- `web_search = "disabled"`: Codex에 내장된 웹 검색은 OpenAI가 호스팅하는 도구에 의존하므로 다른 공급자를 통해서는 동작을 보장할 수 없습니다. 꺼 두세요.

- 공급자는 사용자 수준의 config.toml에만 둘 수 있습니다. 프로젝트의 `.codex/config.toml`에 있는 `model_provider`는 무시됩니다. 공급자 ID는 `openai`, `ollama`, `lmstudio`를 쓸 수 없습니다. Codex가 예약해 둔 이름입니다.

## API 키 설정하기

Codex는 `NEZHAGATE_API_KEY` 환경 변수(위의 `env_key` 값)에서 키를 읽어 `Authorization: Bearer`로 보냅니다. `codex login`은 필요하지 않습니다.

```
export NEZHAGATE_API_KEY=YOUR_API_KEY
codex
```

```
setx NEZHAGATE_API_KEY "YOUR_API_KEY"
```

macOS / Linux에서는 `export` 줄을 `~/.zshrc`나 `~/.bashrc`에 넣어야 계속 유지됩니다. Windows에서는 `setx`로 설정한 뒤 터미널이나 VS Code를 다시 열어야 변숫값을 읽습니다.

## 실행하고 확인하기

아래 명령을 실행하세요. `gateway-ok`라는 응답이 오면 연결된 것입니다:

```
codex exec "Reply with exactly: gateway-ok"
```

- Codex에서 `/status`를 입력하면 현재 모델과 공급자를 볼 수 있습니다.

- 모델을 바꾸려면 `codex -m gpt-6.1-sol`로 시작하거나 config.toml의 `model`을 수정하세요. Codex의 `/model` 메뉴에는 자체 내장 모델만 나열되며 NezhaGate의 모델 목록은 나오지 않습니다.

- 이어서 도구가 필요한 요청(예: 현재 디렉터리의 파일 나열)을 해서 도구 호출도 잘 되는지 확인하세요.

## IDE 확장

VS Code, Cursor, Windsurf의 Codex 확장은 같은 config.toml을 읽습니다: 확장 패널의 톱니바퀴 아이콘 → **Codex Settings** → **Open config.toml**. 수정한 뒤에는 에디터를 다시 시작하고, 터미널에서 실행하지 않은 에디터라면 API 키 변수를 읽을 수 있는지 확인하세요.

## 자주 나오는 오류

**Missing environment variable: `NEZHAGATE_API_KEY`**

Codex를 실행한 프로세스가 이 변수를 보지 못합니다. 실행하기 전에 같은 터미널에서 설정하세요. IDE나 데스크톱 앱은 다시 시작해야 하고, Windows에서는 `setx` 이후 다시 열어야 합니다.

**`wire_api = "chat"` is no longer supported**

예전 설정입니다. `wire_api`를 `"responses"`로 설정하세요.

**unexpected status 401**

키가 잘못되었습니다. 전체를 빠짐없이 복사했는지, 공백이 섞이지 않았는지, 키가 비활성화되지 않았는지 확인하세요.

**unexpected status 404**

`base_url`에 `/v1`이 빠졌습니다. `https://nezhagate.com/v1`이어야 하며, `/responses`는 Codex가 자동으로 붙입니다.

**Claude, Gemini 등 GPT가 아닌 모델을 선택한 뒤 오류가 날 때**

Codex는 `/v1/responses`만 사용하며, NezhaGate는 이 엔드포인트에서 GPT 모델만 제공합니다. 위에 나열된 GPT 모델 중 하나로 바꾸세요.

**stream disconnected before completion**

스트림이 끝나기 전에 끊겼습니다. 대개 로컬 프록시나 네트워크 때문입니다. 다시 시도해 보고, 계속되면 프록시 설정을 확인하세요.