Codex

시작하기 전에

• Codex CLI를 설치하거나 VS Code, Cursor, Windsurf에 Codex 확장을 설치하고, 콘솔에서 API 키를 만드세요.
• Codex는 OpenAI Responses API(/v1/responses)만 사용하며, NezhaGate는 이 엔드포인트에서 GPT 모델을 제공합니다. Claude, Gemini와 그 밖의 모델은 채팅 엔드포인트나 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 키 변수를 읽을 수 있는지 확인하세요.

자주 나오는 오류