책에 포함된 노트OpenAI Codex 활용법: IDE·CLI·클라우드에서 코딩 에이전트로 일하기

문제 해결(트러블슈팅)과 성능 튜닝: 인증, DNS, 설정 충돌, 컨텍스트 관리

2026-03-23Views 11약 8분

Codex를 '가끔 쓰는 도구'로 남겨 두는 가장 흔한 이유는 성능이 아니라 "막힐 때 풀 방법을 모르기" 때문입니다. 반대로, 자주 막히는 지점을 한 번만 체계적으로 정리해 두면 Codex는 금방 '상시 동료'가 됩니다.

이 챕터는 딱 다섯 가지—401/403, base_url 404, Azure 설정 무시, WSL 환경변수 문제, 컨텍스트(/compact)와 모델·추론 강도 조절—를 "증상 → 원인 후보 → 확인법 → 처방" 순서로 다룹니다.

1) 먼저, 진단 순서를 고정하라: 네트워크 → 인증 → 설정 → 컨텍스트

문제가 생기면 사람은 보통 설정부터 뜯어봅니다. 하지만 Codex류 도구는 실패 지점이 대부분 아래 순서로 정리됩니다.

네트워크/엔드포인트: 도메인이 해석되는가(DNS), TLS가 성립하는가, 경로가 맞는가(404)
인증/권한: 키가 유효한가(401), 계정/조직/리소스 권한이 맞는가(403)
설정 충돌: config.toml, 프로파일, 환경변수, CLI 플래그 중 무엇이 이겼는가
컨텍스트/성능: 대화가 길어졌는가, 모델/추론 강도가 과한가, 압축이 필요한가

이 순서를 습관처럼 따르면 "이상한 삽질"이 크게 줄어듭니다.

2) 401과 403: 둘 다 '인증 문제'로 뭉개면 영원히 헤맨다

2.1 401 Unauthorized: "자격 증명이 없거나(혹은 만료/오류)"

401은 요청이 거절된 이유가 인증 실패라는 뜻입니다. 흔히 키가 없거나, 틀렸거나, 만료된 토큰을 썼을 때 발생합니다.¹

현장에서 자주 나오는 원인은 다음과 같습니다.

로그인/토큰이 풀렸는데 세션 재개(resume)만 반복함
쉘/CI 환경에서 OPENAI_API_KEY(또는 해당 도구가 요구하는 키 변수)가 비어 있음
여러 키가 섞여 "다른 프로젝트/조직"의 키로 호출함

확인법은 단순합니다.

현재 쉘에서 키가 정말 잡혀 있는지 확인합니다. (WSL 포함)
키를 새로 발급받아(또는 다시 로그인해) 재시도합니다.
가능하면 "요청을 보내는 프로세스" 안에서 키가 보이는지 확인합니다. (IDE 터미널과 외부 터미널이 분리되는 경우가 흔합니다.)

401은 "내가 증명하지 못했다"이므로, 대부분 내 쪽(클라이언트) 조치로 해결됩니다.

2.2 403 Forbidden: "너인 건 아는데, 그건 못 한다(권한/정책)"

403은 서버가 요청을 이해했고, 당신이 누구인지도 알지만 권한이 없어 거절한다는 뜻입니다.¹

Codex 사용 맥락에서 403은 대개 다음 중 하나입니다.

조직/프로젝트 정책상 특정 모델·기능 사용이 제한됨
Azure OpenAI 사용 시 리소스/배포(deployment) 권한이 없거나, 네트워크 제한(사설 엔드포인트/허용 IP)으로 막힘
엔터프라이즈 환경에서 계정은 맞지만 "승인(Approvals) 없이 실행 불가" 같은 내부 정책이 걸려 있음

403은 재시도한다고 잘 풀리지 않습니다. 서버가 의도적으로 막고 있다는 신호이기 때문입니다.¹ 해결은 보통 권한 부여(관리자), 정책 조정, 네트워크 허용 쪽으로 갑니다.

3) base_url 404: "서버는 살아 있는데 길을 잘못 찾았다"

404는 서버가 "그 경로에 리소스가 없다"고 말하는 것입니다.² Codex에서 404가 자주 보이는 지점은 base_url(또는 엔드포인트) 설정입니다.

3.1 대표 증상

base_url을 바꾼 뒤부터 모든 호출이 404
OpenAI 기본 엔드포인트는 되는데, 프록시/게이트웨이/사내 라우터를 경유하면 404
Azure로 바꿨더니 401/403이 아니라 404부터 뜸

3.2 원인 후보

404의 원인은 단순하지만, 범위가 넓습니다.

경로 오타: /v1 같은 접두 경로 누락/중복
엔드포인트 타입 불일치: "호스트는 맞는데, API가 기대하는 경로 규약이 다른" 서버를 가리킴
DNS/도메인 연결 문제: 도메인이 엉뚱한 곳(기본 페이지/다른 서비스)으로 향하면, 결과가 404로 보이기도 합니다.²

특히 DNS는 "가끔 된다" 같은 간헐적 증상으로 나타나기도 하므로, 의심되면 먼저 고정합니다.

3.3 확인법(가장 빨리 진실에 닿는 순서)

같은 base_url을 브라우저가 아니라 CLI로 직접 확인합니다.

헤더만 보려면 curl -I <base_url>
JSON 응답이 기대되면 curl <base_url>

DNS 확인을 합니다.

nslookup <host> 또는 dig <host>
사내 DNS/개인 DNS/WSL 내부 DNS가 서로 다른 값을 주는지 확인

"내가 입력한 URL이 맞다"는 확신이 들면, 그다음에야 Codex 설정을 봅니다.

404는 설정 파일을 아무리 바꿔도, URL이 틀리면 절대 해결되지 않습니다.

4) "Azure 설정을 했는데 Codex가 무시한다": 설정 충돌을 '우선순위'로 풀기

Azure로 옮겨 타면 설정 항목이 늘고, 그만큼 "내가 바꾼 값이 적용되지 않는다"는 착시가 생깁니다. 이건 도구가 멍청해서가 아니라, 설정이 여러 공급원에서 들어오기 때문입니다.

핵심은 하나입니다.

가장 '강한 레이어'가 최종값을 결정한다.³

Codex에서는 보통 다음이 충돌의 원흉입니다.

CLI 플래그/-c vs config.toml: 커맨드에서 한 번 오버라이드한 값이 기대와 다르게 계속 남아 있는 것처럼 느껴짐
프로파일(Profiles) 전환 실수: 로컬에서는 default, CI에서는 ci 같은 프로파일을 쓰는데, 한쪽만 고쳐 놓고 "왜 안 되지?"가 됨
환경변수 잔존: 예전에 내보낸 OPENAI_BASE_URL, OPENAI_API_KEY, AZURE_OPENAI_API_KEY 등이 남아 설정 파일 변경을 덮어씀
WSL/Windows 이중 환경: Windows 호스트와 WSL이 서로 다른 값을 갖고 있는데, 확장/터미널이 '다른 쪽'을 참고함

4.1 확인법: 충돌을 '눈으로 보이게' 만들기

실행 전에 printenv | rg 'OPENAI|AZURE|CODEX'(또는 env)로 관련 변수를 확인합니다.
~/.codex/config.toml과 프로젝트의 .codex/config.toml(있다면)을 모두 확인합니다.
의심되면 환경변수를 잠깐 비우고 재현합니다.

unset OPENAI_BASE_URL OPENAI_API_KEY AZURE_OPENAI_API_KEY

4.2 처방: 충돌을 '없애는' 방식으로 고친다

확실히 파일로 관리할 값(예: model_provider, base_url)은 환경변수에 중복으로 두지 않습니다.
반대로 CI에서만 쓰는 값(키)은 환경변수/시크릿으로 통일하고, 로컬 파일에는 넣지 않습니다.
Azure 전환처럼 큰 변경을 할 때는 한 번은 "전부 명시"한 상태로 성공시키고(엔드포인트/키/배포명), 그다음에 중복을 걷어냅니다.

요령: '설정이 먹나?'를 확인할 때는, 다른 요소를 줄여야 합니다. 프로파일을 하나로 고정하고, 환경변수도 최소로 두고, 가장 짧은 프롬프트로 codex exec "hello" 같은 헬스체크를 통과시키는 게 가장 빠릅니다.

5) WSL에서 자주 터지는 환경변수/CLI 문제: '영속화'와 '개행문자'

WSL은 편하지만, 설정이 Windows와 분리되어 있다는 사실을 잊는 순간 문제가 시작됩니다.

5.1 "재부팅하면 변수가 사라져요": 영속화 위치를 정하라

WSL에서 환경변수를 지속하려면, 보통 셸 초기화 파일에 내보내야 합니다. 배포판/셸에 따라 차이가 있지만, 가장 흔한 선택지는 ~/.bashrc, ~/.profile 같은 로그인/인터랙티브 초기화 스크립트입니다.⁴

중요한 건 "어디에 넣었는지 팀 규칙을 정하는 것"입니다. 개인마다 다른 파일에 흩어져 있으면, 재현도 어렵고 온보딩도 느려집니다.

5.2 "값이 맞는데도 이상하게 실패": Windows 도구 출력의 `r`(CRLF) 함정

WSL에서 az 같은 도구를 쓰는데, 사실은 WSL용이 아니라 Windows에 설치된 실행 파일을 WSL이 호출하는 경우가 있습니다. 이때 출력이 Windows 스타일 개행(CRLF)이라서, 변수 끝에 r이 붙고 URL/태그/토큰이 깨지는 문제가 실제로 발생합니다.⁵

가장 빠른 확인은 다음입니다.

which az처럼 실행 파일 경로를 확인
값이 의심되면 echo "$VAR" | cat -A로 보이지 않는 문자를 확인

처방은 단순합니다. 가능하면 WSL 안에 리눅스용 CLI를 설치해 그쪽을 쓰거나, 출력 정규화(tr -d 'r')를 한 번 거치도록 습관화합니다.⁵

5.3 WSL 설정을 바꿨는데 적용이 안 됨: "완전 재시작" 규칙

WSL은 설정 파일을 바꿔도 즉시 반영되지 않는 경우가 있습니다. 문서에서도 WSL이 완전히 종료됐다가 다시 시작되어야 설정이 적용된다고 안내합니다.⁶ 빨리 적용하려면 PowerShell에서 wsl --shutdown으로 전체를 재시작하는 방법이 있습니다.⁶

이 규칙을 모르면 "설정이 안 먹는다"는 오해로 이어지기 쉽습니다.

6) 성능 튜닝의 시작: /compact로 '대화의 무게'를 줄인다

Codex가 느려졌을 때, 모델을 바꾸기 전에 먼저 의심해야 하는 건 컨텍스트가 너무 무거워진 것입니다. 대화가 길어질수록 모델은 더 많은 텍스트를 읽고(입력), 더 많은 상태를 유지해야 하며, 그만큼 비용과 지연이 늘어납니다.

6.1 /compact를 언제 쓰나

다음 신호가 오면 압축할 타이밍입니다.

이전 합의(요구사항/제약)가 많아서, 매번 "처음부터 다시 설명"하게 된다
로그/스택트레이스/코드 블록이 반복해서 누적된다
간단한 수정인데 응답이 체감상 급격히 느려진다

/compact의 요지는 간단합니다. 지금까지의 대화를 '작업에 필요한 형태로 요약'해 토큰을 줄이고, 이후 지시가 덜 흔들리게 만드는 것입니다.

단, 압축은 기억을 "버리는" 행위이기도 합니다. 그래서 압축 직후에는 다음을 짧게 재주입하는 습관이 좋습니다.

현재 목표(무엇을 고치는지)
금지사항/제약(예: 특정 디렉터리는 수정 금지)
완료 조건(예: 테스트 통과, 특정 파일에만 변경)

6.2 모델·추론 강도(Reasoning effort)를 언제 올리고 내리나

성능 튜닝은 대개 두 축입니다.

모델 크기/등급: 더 작은 모델은 빠르고 저렴하지만, 복잡한 추론·대규모 리팩터링에서 흔들릴 수 있습니다.
추론 강도: 강도를 올리면 더 신중해지지만(대체로 품질↑), 지연과 비용이 늘어납니다.

현장에서 잘 먹히는 규칙은 이렇습니다.

"정확한 편집" 위주(작은 변경, 포맷, 간단한 테스트 추가)면 추론 강도를 낮추고 빠르게 반복합니다.
"원인 추적/설계 판단" 위주(복잡한 버그, 아키텍처 변경)면 추론 강도를 올리고, 대신 승인(Approvals)·샌드박스 규칙을 더 빡빡하게 가져갑니다.

즉, 느릴 때는 무조건 모델을 낮추기보다, 먼저 /compact로 입력을 줄이고, 그다음에 작업 성격에 맞춰 모델·강도를 조절하는 편이 안정적입니다.

7) 빠른 체크리스트: 자주 막히는 5종 세트

문제가 생기면 아래를 위에서 아래로 그대로 실행해 보세요.

401: 키/로그인 상태 확인 → "요청 프로세스"에서 환경변수 확인 → 재로그인/키 교체¹
403: 권한/정책 문제로 가정 → 조직/리소스 접근권 요청 → 네트워크 제한(허용 IP/프라이빗) 확인¹
base_url 404: curl -I로 엔드포인트 직접 확인 → DNS 확인(dig/nslookup) → 경로 규약(접두 경로) 재점검²
Azure 설정 무시: 환경변수 vs config.toml vs 프로파일 충돌 제거 → 최종 적용값 출력/로그로 확인 → 하나의 소스만 남기기³
WSL 환경변수 문제: 영속화 파일 점검⁴ → which로 Windows 실행 파일 혼입 확인 및 r 제거⁵ → 필요 시 wsl --shutdown으로 재시작⁶