오픈소스 Codex CLI + Ollama로 gpt-oss를 로컬에서 토큰 비용 0으로 돌리기
오픈소스 Codex CLI + Ollama로 gpt-oss를 로컬에서 토큰 비용 0으로 돌리기 — 무엇이 무료이고 무엇이 아닌가
터미널에서 AI 코딩 에이전트를 쓰면서 "이번 달 API 비용이 또 나왔네"라고 생각해본 적 있으신가요? OpenAI의 오픈소스 Codex CLI에 --oss 플래그 하나를 붙이면 로컬 Ollama 서버로 연결이 바뀌고, 그 순간부터 API 토큰 과금은 0이 됩니다. 단, "완전히 무료"라는 말에는 중요한 전제가 붙습니다. 하드웨어가 있어야 한다는 것이죠.
이 글에서는 Codex CLI가 정확히 무엇인지, gpt-oss 오픈웨이트 모델이 어떻게 동작하는지, 그리고 로컬 실행의 진짜 비용 범위를 팩트 기반으로 정리합니다. 2025년 8월에 도입된 기능을 지금 시점(2026년 5월)에서 차분하게 살펴볼게요.
Codex CLI란 무엇인가 — 혼동하기 쉬운 3종 구분
"OpenAI Codex"라는 이름을 검색하면 서로 다른 세 가지 제품이 나옵니다. 로컬 무료 실행 얘기를 할 때 어떤 Codex를 가리키는지 먼저 짚고 넘어가야 합니다.
| 명칭 | 정체 | 로컬·무료 실행 가능? |
|---|---|---|
| Codex CLI | Rust로 작성된 오픈소스 터미널 코딩 에이전트 (github.com/openai/codex, 2025-04-16 출시) | 예 — --oss + Ollama로 토큰 과금 0 |
| Codex 클라우드 에이전트 | ChatGPT에 통합된 웹 기반 비동기 코딩 에이전트 | 아니오 — ChatGPT Plus($20/월) 또는 API 크레딧 필요 |
| gpt-5-codex 계열 모델 | Codex에 최적화된 OpenAI 호스팅 모델 | 아니오 — OpenAI API 종량 과금 |
이 글에서 다루는 것은 오직 첫 번째, Codex CLI입니다. ChatGPT 웹에서 쓰는 Codex 에이전트나 OpenAI API의 codex 모델 엔드포인트와는 완전히 별개의 오픈소스 프로젝트입니다.
Codex CLI 핵심 한 줄: Rust로 만들어진 터미널 코딩 에이전트로, 2025년 4월 16일 오픈소스 공개됐습니다. 파일을 읽고 코드를 수정하며 테스트를 실행하는 에이전트 루프를 로컬에서 돌릴 수 있습니다. 기본값은 OpenAI API를 쓰지만,
--oss플래그 하나로 로컬 추론 서버로 전환됩니다.
gpt-oss란 무엇인가 — Apache 2.0 오픈웨이트 모델
--oss 플래그의 실제 추론을 담당하는 모델이 gpt-oss입니다. 몇 가지 핵심 사실을 정리합니다.
- 출시일: 2025년 8월 5일. OpenAI가 gpt-oss-20b와 gpt-oss-120b를 동시에 공개했고, 같은 날 Ollama도 공식 통합 지원을 발표했습니다.
- 라이선스: Apache 2.0. 상업적 사용, 수정, 재배포가 모두 허용됩니다.
- 다운로드: Hugging Face에서 무료로 받을 수 있으며, Ollama 라이브러리에서는
ollama pull gpt-oss:20b한 줄로 다운로드됩니다. - 규모: 20B 파라미터(20b)와 120B 파라미터(120b) 두 가지입니다.
gpt-oss는 임의의 오픈소스 LLM이 아니라 OpenAI가 Codex CLI와의 통합을 염두에 두고 공개한 모델입니다. 코드 이해와 생성에 특화된 아키텍처를 갖고 있습니다.
codex --oss가 작동하는 방식 — Ollama 연결 메커니즘
--oss 플래그를 붙이면 Codex CLI 내부에서 model_provider="oss"로 설정이 바뀝니다. 실행 흐름은 다음과 같습니다.
- Codex CLI가 Ollama가 실행 중인지 확인합니다 (
http://localhost:11434) - OpenAI 호환 엔드포인트(
/v1)로 요청을 보냅니다 - 기본값으로
gpt-oss-20b가 추론을 수행합니다
기본 실행 방법:
# Ollama 먼저 실행 (백그라운드)
ollama serve
# 기본 모델(gpt-oss-20b)로 Codex CLI 실행
codex --oss
# 120b 모델로 지정 실행
codex --oss -m gpt-oss:120b
config.toml 방식 (영구 설정):
~/.codex/config.toml에 아래 내용을 추가하면 매번 플래그를 붙이지 않아도 됩니다.
[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
[profiles.ollama]
model = "gpt-oss:120b"
model_provider = "ollama"
이후 codex --profile ollama로 실행합니다. 로컬 모델은 클라우드보다 응답이 느릴 수 있으므로, 타임아웃 설정도 함께 늘려두는 것이 좋습니다.
[profiles.ollama]
model = "gpt-oss:120b"
model_provider = "ollama"
stream_idle_timeout_ms = 600000 # 10분
Ollama가 OpenAI wire API 형식을 그대로 구현하고 있어서, Codex CLI는 로컬 서버를 OpenAI API 서버처럼 인식합니다. 이 덕분에 gpt-oss 외의 Ollama 호환 모델도 이론적으로 연결할 수 있습니다.
무료의 진짜 범위 — 토큰 과금 0과 하드웨어 비용은 다른 이야기
"로컬 실행은 무료"라는 말이 맞는 부분과 틀린 부분을 구분해야 합니다.
| 비용 항목 | 로컬(Codex CLI + Ollama + gpt-oss) | 클라우드(ChatGPT Codex / OpenAI API) |
|---|---|---|
| Codex CLI 도구 | 무료 (오픈소스) | — |
| API 토큰 과금 | 0원 (로컬 추론) | API 종량 또는 구독 |
| gpt-oss 모델 라이선스 | 무료 (Apache 2.0) | 해당 없음 |
| 하드웨어 | 별도 비용 | OpenAI 인프라에 포함 |
| 전기/유지비 | 사용자 부담 | OpenAI 부담 |
정확한 표현은 "API 토큰 비용은 0, 단 자기 하드웨어가 있어야 한다"입니다. 이미 충분한 로컬 장비를 갖고 있는 개발자라면 실질적으로 추가 비용 없이 쓸 수 있습니다. 반면 하드웨어를 새로 마련해야 한다면 투자 회수를 따져봐야 합니다.
하드웨어 요건 — 20b와 120b의 현실적인 차이
gpt-oss 모델을 로컬에서 돌리려면 모델 크기에 맞는 메모리가 필요합니다.
gpt-oss-20b (20B 파라미터)
- 필요 메모리: 약 16GB RAM (또는 VRAM)
- 실용 환경: 최신 Mac(M1/M2/M3 32GB 이상), 소비자용 GPU(RTX 3090 등)
- 특징: 일반 개발 작업에 충분한 품질, 응답 속도 현실적
gpt-oss-120b (120B 파라미터)
- 필요 메모리: 단일 80GB GPU급 또는 멀티 GPU 분산
- 실용 환경: A100 80GB, H100, 또는 여러 장의 소비자용 GPU 병렬 구성
- 특징: 클라우드 품질에 근접하지만 일반 개발자 환경에서 접근이 어려움
대부분의 개발자가 먼저 시도할 수 있는 선택지는 gpt-oss-20b입니다. Apple Silicon Mac 사용자라면 16GB 이상 통합 메모리 모델에서 바로 시작할 수 있습니다. gpt-oss-120b는 연구 환경이나 클라우드 VM을 쓰는 경우가 아니면 진입 장벽이 높습니다.
언제 유료 클라우드를 써야 하는가 — 로컬 vs 클라우드 선택 기준
로컬 실행이 항상 최선은 아닙니다. 아래 기준으로 선택을 나눌 수 있습니다.
로컬 실행이 유리한 경우
- 코드베이스에 민감한 정보(API 키, 사내 로직 등)가 포함된 경우
- 반복적인 소규모 수정 작업이 많아 API 비용이 빠르게 쌓이는 경우
- 이미 충분한 로컬 하드웨어를 갖추고 있는 경우
- 오프라인 환경에서 작업해야 하는 경우
클라우드(ChatGPT Codex 에이전트 / OpenAI API)가 유리한 경우
- 최신 대규모 모델(gpt-5-codex 계열)의 성능이 필요한 경우
- 하드웨어 없이 바로 시작하고 싶은 경우
- 비동기 장시간 에이전트 작업(ChatGPT 웹 Codex 에이전트)이 필요한 경우
- 팀 단위 협업으로 일관된 추론 품질이 필요한 경우
클라우드 Codex 에이전트(ChatGPT Plus 기반)는 별도의 서비스로, 백그라운드에서 장시간 돌아가는 비동기 코딩 작업에 특화돼 있습니다. 이 부분은 --oss로 대체되지 않습니다.
선택의 실용적 기준: 보안·비용이 우선이면 로컬, 품질·편의가 우선이면 클라우드. 두 가지를 번갈아 쓰는 하이브리드 접근도 현실적입니다. 로컬로 초안을 잡고 클라우드로 정밀 리뷰하는 방식이죠.
정리 — 핵심 사실 체크리스트
2025년 8월부터 자리 잡은 이 기능 묶음을 정리합니다.
- Codex CLI는 오픈소스 터미널 코딩 에이전트(Rust, github.com/openai/codex)로, ChatGPT의 클라우드 Codex 에이전트와 완전히 별개입니다
codex --oss플래그 하나로 Ollama 로컬 서버로 연결이 전환됩니다- 기본 추론 모델은 gpt-oss-20b이며, gpt-oss는 2025년 8월 5일 Apache 2.0으로 출시됐습니다
- API 토큰 과금은 실제로 0입니다 — 로컬 추론이므로 OpenAI 서버에 요청이 가지 않습니다
- 단, 하드웨어 비용은 별도입니다: 20b≈16GB RAM, 120b≈80GB GPU급
~/.codex/config.toml로 프로필을 영구 설정할 수 있으며,stream_idle_timeout_ms로 느린 로컬 모델 타임아웃을 조정할 수 있습니다
개인 개발 환경에서 API 비용이 신경 쓰이거나 코드를 외부로 내보내고 싶지 않은 분들에게 지금 당장 시도해볼 수 있는 옵션입니다.
자주 묻는 질문 (FAQ)
Q: codex --oss를 실행했는데 연결이 안 됩니다. 왜 그런가요?
Ollama가 실행 중이지 않은 경우가 가장 흔합니다. ollama serve로 서버를 먼저 켜고, http://localhost:11434에 응답이 오는지 확인한 뒤 Codex CLI를 실행하세요. Ollama가 실행 중인데도 안 된다면 gpt-oss 모델이 다운로드돼 있는지 ollama list로 확인하세요.
Q: gpt-oss 말고 다른 Ollama 모델(예: llama, qwen)을 Codex CLI에 연결할 수 있나요?
가능합니다. Codex CLI는 Ollama의 OpenAI 호환 엔드포인트(http://localhost:11434/v1)를 통해 연결하므로, Ollama에서 지원하는 모델이라면 config.toml의 model 필드만 바꿔서 연결할 수 있습니다. 다만 코딩 에이전트 루프에 최적화된 모델 형태가 아니면 결과 품질이 달라질 수 있습니다.
Q: ChatGPT Plus 구독자인데, ChatGPT의 Codex 에이전트와 Codex CLI 중 무엇을 써야 하나요?
용도가 다릅니다. ChatGPT의 Codex 에이전트는 웹 브라우저에서 백그라운드로 장시간 돌아가는 비동기 작업에 강합니다. Codex CLI는 터미널에서 직접 코드를 편집하고 테스트를 돌리는 인터랙티브 에이전트입니다. 빠른 인터랙티브 작업은 CLI, 오래 걸리는 독립 작업은 ChatGPT Codex 에이전트가 적합합니다.
