openai-codex 첫 베타, 지금 써도 괜찮은가?

공식 openai-codex 첫 베타: v0.1.0b1 고정, 스레드 시작, 베타 주의사항 회피 방법. 2026년 5월 28일 출시.

May 30, 2026

openai-codex v0.1.0b1 주요 내용

openai-codex v0.1.0b1은 OpenAI가 공식적으로 배포한 첫 번째 Python SDK로, Codex 에이전트 기능을 애플리케이션 코드에 직접 내장할 수 있습니다. 이는 JSONL over stdin/stdout 방식으로 CLI 바이너리를 감싸던 초기 커뮤니티 패키지 openai-codex-sdk와는 별개이며, 해당 패키지는 2025년 12월 처음 등장했습니다 . 공식 베타는 2026년 5월 28일 Codex CLI v0.135.0과 함께 출시되었으며, SDK 버전은 CLI를 직접 추적합니다. 0.1.0b1과 0.1.0b2 모두 같은 날 Apache-2.0 라이선스로 PyPI에 게시되었습니다 .

한눈에 보기: openai-codex v0.1.0b1은 Codex 에이전트 스레드를 위한 OpenAI 공식 Python SDK로, 2026년 5월 28일 Apache-2.0 라이선스로 출시되었습니다. pip install openai-codex==0.1.0b1로 설치할 수 있으며, Python ≥3.10이 필요합니다. CLI 바이너리가 자동으로 번들되므로 별도 CLI 설치는 불필요합니다.

공개 릴리스 전, 세 개의 PR이 API 표면을 안정화했습니다: 스키마 생성 타입(PR #18862, 2026년 4월 21일) , 런타임 wheel 배포(PR #18865), Codex 고정 버전 관리(PR #18996, 2026년 4월 27일) . 패키지는 개발 상태 4(베타)로 출시되며, 공개 API는 1.0 이전까지 안정적이지 않습니다.

이번 릴리스의 핵심 신기능은 스레드 레벨에서 기존 --profile 플래그 방식을 대체하는 세 가지 샌드박스 프리셋입니다:

프리셋	파일시스템 효과	권장 용도
`read_only`	읽기 전용, 쓰기 불가	감사, 검사, 코드 설명 작업
`workspace_write`	워크스페이스 루트 쓰기 권한 (기본값)	일반 에이전틱 코딩 작업
`full_access`	파일시스템 무제한 접근	자기 수정 실험 — 격리된 컨테이너 전용

설치 및 사전 요구사항

openai-codex v0.1.0b1: First Beta Install and Thread Walkthrough

유일한 필수 요구사항은 Python ≥3.10입니다 — 3.10, 3.11, 3.12, 3.13에서 테스트되었습니다. Codex CLI를 별도로 설치할 필요가 없으며, 패키지가 openai-codex-cli-bin을 고정된 런타임 의존성으로 자동 설치합니다 . 동일한 출시일(2026년 5월 28일)을 가진 0.1.0b2로 자동 해석되는 것을 막으려면 정확한 버전을 고정해 설치하세요 :

pip install openai-codex==0.1.0b1

네 가지 인증 방식을 사용할 수 있습니다:

기존 CLI 자격 증명 재사용 — 로컬 개발에 가장 간단한 방법으로, 인자 없이 Codex()를 생성하면 캐시된 자격 증명을 자동으로 가져옵니다.
API 키 — 생성 후 codex.login_api_key('sk-...')를 호출하거나 환경 변수에 OPENAI_API_KEY를 설정합니다. CI/CD 파이프라인에 적합합니다.
브라우저 로그인 — codex.login_chatgpt()가 브라우저에서 열 인증 URL을 반환합니다. 대화형 터미널에 적합합니다.
기기 코드 흐름 — codex.login_chatgpt_device_code()가 인증 URL과 사용자 코드를 반환합니다. 헤드리스 서버에 적합합니다.

기기 코드 및 API 키 흐름은 2026년 5월 20일 출시된 CLI v0.132.0에서 정식 지원으로 격상되었습니다 . 이전 CLI 설치에서 자격 증명을 재사용하는 경우, 명시적인 로그인 단계를 실행하세요 — 자동 실패는 알려진 문제입니다(아래 주의사항 참조).

임포트에서 첫 스레드까지: 단계별 안내

아래 코드는 예시용입니다 — codex_app_server 모듈은 openai-codex 패키지 설치 시 자동으로 포함되지만, 작성 시점의 테스트 환경에서는 사용할 수 없었습니다. 먼저 설치 주석을 실행한 뒤 코드를 실행하세요. 시작 가이드에 완전히 실행된 예제가 있습니다.

"""First beta install: python -m pip install openai-codex==0.1.0b1"""

from codex_app_server import Codex


with Codex() as codex:
    thread = codex.thread_start(model="gpt-5.4")

    first = thread.run("Reply with exactly: first beta thread started")
    print("first:", first.final_response)

    followup = thread.run("Reply with exactly: same thread follow-up")
    print("followup:", followup.final_response)

단계별 설명:

임포트 및 열기. with Codex() as codex: 컨텍스트 매니저는 진입 시 로컬 JSON-RPC 앱 서버를 시작하고, 종료 시 깔끔하게 닫습니다. 서버 라이프사이클을 수동으로 관리할 필요가 없습니다.
스레드 시작. codex.thread_start(model="gpt-5.4")는 지속적인 대화 단위를 생성합니다. 지원 모델은 gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, gpt-5.3-codex-spark(ChatGPT Pro 전용)입니다 . sandbox="read_only"를 전달하면 스레드 전체 수명 동안 에이전트의 파일시스템 접근 범위를 제한할 수 있습니다.
턴 실행. thread.run("...")은 프롬프트를 전송하고 완료될 때까지 블로킹합니다. 일반 문자열은 자동으로 TextInput으로 변환되며, 비전 프롬프트에는 ImageInput(url=...)이나 LocalImageInput(path=...)을 전달하세요.
결과 확인. 반환된 TurnResult는 final_response(str 또는 None), items(ThreadItem 목록), usage(ThreadTokenUsage), duration_ms, started_at, completed_at을 노출합니다 . 첫 실행에서 result.usage와 result.duration_ms를 로깅해 두세요 — 모델이나 샌드박스 프리셋을 바꾸기 전에 기준값을 확보해야 합니다.

비동기 환경에서는 Codex 대신 AsyncCodex를 사용하고, with / thread.run()을 async with / await thread.run()으로 교체하세요. 지연 초기화 덕분에 임포트 시 오버헤드가 미미합니다. 나머지 인터페이스는 동일하므로 FastAPI 라우트나 asyncio 파이프라인에 바로 적용할 수 있습니다:

import asyncio
from openai_codex import AsyncCodex

async def main():
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4-mini")
        result = await thread.run("Generate a docstring for utils.py")
        print(result.final_response)

asyncio.run(main())

주의 사항과 베타 제약

프로토타입을 넘어서기 전에 알아두어야 할 다섯 가지:

설치 당일 버전 충돌. v0.1.0b1과 v0.1.0b2는 PyPI 출시일이 2026년 5월 28일로 동일합니다 . 명시적인 버전 고정 없이는 pip이 자동으로 더 높은 패치 버전을 선택할 수 있습니다. 테스트한 버전으로 항상 고정하세요: requirements.txt에 openai-codex==0.1.0b1을 지정합니다.
불안정한 공개 API. 개발 상태 4(베타)이므로 TurnResult 필드명, ThreadTokenUsage 구조, 샌드박스 프리셋 식별자가 1.0 이전에 변경될 수 있습니다 . 버전을 올리기 전마다 Codex 변경 로그를 확인하세요.
큰 설치 용량. 번들된 CLI 바이너리가 플랫폼에 따라 약 50~100 MB를 추가합니다 . 바이너리 레이어는 변경 빈도가 낮으므로, Docker 빌드 초반에 분리해 CI 캐시를 효율적으로 유지하세요.
full_access 문서 미비. full_access 프리셋 문서는 출시 당시 미완성 상태였습니다. 실제 저장소에 적용하기 전에 반드시 격리된 컨테이너 안에서 이 프리셋으로 에이전트 루프를 테스트하세요.
오래된 인증 정보 오류. v0.132.0 이전(2026년 5월 20일 이전 ) CLI 버전에 캐시된 인증 정보는 새로운 인증 흐름에서 오류 없이 실패할 수 있습니다. codex.login_api_key('sk-...')를 실행하거나 디바이스 코드 플로우를 명시적으로 실행해 인증 정보를 새로 갱신하세요.

더 나아가기: 비동기·이미지 입력·스레드 설정

기본 스레드가 동작하면, 이 네 가지 패턴이 가장 생산적인 다음 단계입니다:

비동기 전환. FastAPI나 asyncio 루프와 통합하려면 Codex를 AsyncCodex로 교체하세요. 지연 초기화 덕분에 임포트 오버헤드가 낮으며, 나머지 인터페이스는 동일합니다.
스크린샷→수정 루프. thread.run()에 텍스트 프롬프트와 함께 LocalImageInput(path='screenshot.png')을 전달하세요. UI 회귀 트리아지에 유용합니다 — 모델이 diff 설명 없이 스크린샷을 직접 확인합니다.
서브에이전트 모델 라우팅. 지연 시간과 비용이 중요한 고빈도 서브태스크에는 gpt-5.4-mini를 사용하고 , 외부 계획·추론 레이어에는 gpt-5.4 또는 gpt-5.5를 남겨두세요.
태스크별 샌드박스 범위 설정. 안전한 검사·설명 태스크에는 thread_start()에 sandbox='read_only'를 전달하고, 자기 수정 실험에는 full_access를 일회용 컨테이너에서만 사용하세요.

SDK API 참조에는 세밀한 실행 중 제어를 위한 TurnHandle과 AsyncTurnHandle도 문서화되어 있습니다: 이벤트 스트리밍, 실행 중인 턴에 업데이트된 지시 전달, 강제 중단 등이 가능하며 — 체크포인트로 불필요한 토큰 소비를 줄여야 하는 긴 에이전트 루프에 유용합니다.

자주 묻는 질문

openai-codex Python 패키지를 사용하기 전에 Codex CLI를 별도로 설치해야 하나요?

아닙니다. openai-codex 패키지는 openai-codex-cli-bin을 고정된 런타임 의존성으로 자동 설치합니다. CLI 바이너리는 SDK에 번들링되어 관리되므로 별도의 설치 과정이 필요하지 않습니다 .

openai-codex v0.1.0b1이 지원하는 Python 버전은 무엇인가요?

Python 3.10, 3.11, 3.12, 3.13을 지원합니다. 3.10 미만 버전은 지원하지 않습니다 .

v0.1.0b1과 v0.1.0b2의 차이는 무엇인가요?

두 버전 모두 2026년 5월 28일 PyPI에 등록되었습니다 . 작성 시점 기준으로 두 버전을 구분하는 공개 릴리스 노트는 없습니다. SDK는 CLI 버전을 추적하며 패치 버전 변경 시 번들된 바이너리 동작이 달라질 수 있으므로, 테스트한 버전을 requirements.txt에 고정하고 신중하게 업그레이드하는 것이 가장 안전합니다.

openai-codex v0.1.0b1을 프로덕션에 사용해도 되나요?

개발 상태 4(베타)는 공개 API가 안정적이지 않음을 의미합니다. TurnResult 필드명, ThreadTokenUsage 구조, 샌드박스 프리셋 식별자는 1.0 출시 전에 변경될 수 있습니다. 정확한 버전을 고정하고, API 표면을 불안정한 것으로 취급하며, 안정적인 릴리스가 태그되기 전까지는 핵심 프로덕션 경로에서 사용하지 않는 것을 권장합니다.

Codex와 AsyncCodex의 차이는 무엇인가요?

Codex는 동기식이며 컨텍스트 매니저로 안전하게 사용할 수 있어 스크립트, CLI, 동기식 프레임워크에 적합합니다. AsyncCodex는 지연 초기화를 지원하는 비동기 대응 클래스로, FastAPI와 같은 asyncio 기반 프레임워크를 위해 설계되었습니다. 스레드 및 턴 인터페이스는 두 클래스 모두 동일합니다 .

다음 단계로 만들어볼 것들

첫 번째 스레드가 실행되면, 복잡한 기능을 추가하기 전에 실제 작업 몇 가지에 걸쳐 result.usage와 result.duration_ms를 기록해 두는 것이 가장 유용한 다음 단계입니다. 이 기준값을 통해 모델이나 샌드박스 프리셋을 전환할 때 토큰과 지연 시간 측면에서 실제로 얼마나 차이가 나는지 파악할 수 있으며, 이는 나중에 재구성하기 어려운 정보입니다.

그다음으로 일찍 살펴볼 만한 두 가지 패턴은 스크린샷 기반 워크플로를 위한 LocalImageInput 비전 경로와, 실행 도중 중단으로 상당한 토큰 비용을 절약할 수 있는 장시간 에이전틱 루프를 위한 TurnHandle 스트리밍입니다. 두 기능 모두 SDK API 레퍼런스와 Python SDK 저장소에서 다루고 있습니다.

0.1.0b1과 0.1.0b2가 같은 날 출시된 만큼, 이 베타 단계에서의 릴리스 주기는 빠릅니다. Codex 변경 로그를 구독하고 버전을 올리기 전에 반드시 확인하세요 — TurnResult의 필드명이 변경되더라도 런타임에서 눈에 띄게 알려주지 않습니다.

최종 업데이트: 2026-05-31. openai-codex v0.1.0b1 및 2026년 5월 28일 출시된 Codex CLI v0.135.0 기준.