openai-codex Python SDK v0.1.0b2: 설치, 인증, 실행 가이드

v0.1.0b2 한눈에: 샌드박스 프리셋과 설정 클래스 이름 변경

2026년 5월 28일 GitHub 태그 python-v0.1.0b2로 릴리스된 openai-codex v0.1.0b2는 OpenAI가 Codex 에이전트를 프로그래밍 방식으로 구동하기 위해 제공하는 Python SDK의 두 번째 공개 베타입니다. v0.1.0b1 대비 가장 큰 변화는 세 가지 이름이 지정된 Sandbox 프리셋 — READ_ONLY, WORKSPACE_WRITE, FULL_ACCESS — 의 도입으로, 기존에 직접 구성해야 했던 원시 권한 문자열을 대체합니다. 부수적인 변경 사항으로 AppServerConfig가 CodexConfig로 교체되었는데, 이는 동작 차이 없이 한 줄 찾기-바꾸기로 처리되는 수준입니다 . 패키지는 0.132.0으로 고정된 openai-codex-cli-bin에 의존하며 바이너리는 wheel에 포함되지 않습니다. 또한 이번 버전은 openai-codex 패키지 이름으로 공개적으로 접근 가능한 첫 번째 릴리스이기도 합니다. 이 이름은 2026년 5월 16~18일경 Codex CLI v0.131.0에서 내부 모듈 codex_app_server로부터 변경된 것입니다 .

핵심 요약: Python 3.10 이상에서 pip install openai-codex==0.1.0b2로 설치합니다. v0.1.0b1 대비 핵심 추가 사항은 파일시스템 접근을 제어하는 세 가지 이름이 지정된 Sandbox 프리셋입니다. 헤드리스 인증은 codex.login_api_key('sk-...')로 처리합니다. 정확한 버전을 고정하세요 — 베타 간 API 표면이 변경되며 안정성은 보장되지 않습니다.

이전 코드에서 AppServerConfig를 사용했다면 CodexConfig로 이름만 바꾸면 됩니다 — 그 외에는 아무것도 깨지지 않습니다. 또한 PyPI에 2026년 3월 기준 버전 0.117.0으로 등록된 별도 패키지 codex-sdk-python은 CLI 런타임 버전에 맞춰 독자적인 버전 트랙을 따르는 다른 라이브러리입니다. 두 패키지를 동시에 설치하지 마세요.

사전 요구 사항 및 pip 설치

SDK는 Python 3.10 이상이 필요합니다 . 먼저 버전을 확인한 후 정확한 베타 버전으로 고정해 설치합니다:

python --version
pip install openai-codex==0.1.0b2

wheel은 openai-codex-cli-bin을 의존성으로 가져오지만 Codex 바이너리를 직접 포함하지는 않습니다. macOS, Linux, 일반적인 CI 러너 등 대부분의 환경에서는 해당 companion 패키지를 통해 바이너리가 자동으로 해결됩니다. 명시적 제어가 필요한 컨테이너나 Jupyter 노트북 환경에서는 다른 호출보다 먼저 바이너리를 초기화하세요:

from openai_codex import Codex

Codex.install(version="rust-v0.132.0")

사용자 측에서는 Rust 툴체인이나 추가적인 시스템 의존성이 필요하지 않습니다 — 바이너리는 미리 컴파일되어 제공됩니다. 설치가 올바르게 완료되었는지 확인합니다:

python -c "from openai_codex import Codex, Sandbox, CodexConfig; print('OK')"

스레드 시작과 응답 읽기

SDK는 스레드를 중심으로 구성됩니다. 각 Thread는 ~/.codex/sessions에 저장되는 영속 세션에 대응됩니다. thread.run() 호출 한 번이 하나의 턴 — 프롬프트 하나 입력, TurnResult 하나 출력입니다. TurnResult는 .final_response(에이전트의 텍스트 답변), .collected_items(순서대로 나열된 모든 중간 도구 호출), .timing, .usage(토큰 수)를 제공합니다 . 동기 경로를 단계별로 살펴봅니다.

1. 적합한 샌드박스 프리셋을 선택합니다. FULL_ACCESS가 기본값이지만 파일시스템 접근을 무제한 허용합니다. 프로젝트를 건드리는 대부분의 코딩 작업에는 WORKSPACE_WRITE(현재 작업 디렉터리 내부만 쓰기 허용)가 적절합니다. 쓰기가 없어야 하는 분석·감사 작업에는 READ_ONLY를 사용하세요.
2. 결과를 확인합니다. result.final_response는 에이전트의 최종 텍스트입니다. result.collected_items는 모든 중간 도구 호출을 제공하므로, 에이전트가 실제로 읽거나 수정한 내용을 정확히 감사하는 데 유용합니다.

나중 세션에서 스레드를 재개합니다. 첫 번째 턴 이후 result.thread_id를 저장하세요. 새 Python 프로세스에서 codex.resume_thread(thread_id)를 호출합니다:

thread_id = result.thread_id  # persist this string

# in a later session:
thread = codex.resume_thread(thread_id)
result = thread.run("Continue from where we left off.")

컨텍스트 매니저를 열고 스레드를 시작합니다. 항상 Codex()를 컨텍스트 매니저로 사용하세요 — 내부 프로세스 생명주기를 관리합니다. thread_start()에서 Sandbox 프리셋을 전달합니다:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.WORKSPACE_WRITE)
    result = thread.run("Explain this repository in three bullets.")
    print(result.final_response)
    print(result.usage)   # token counts

비동기 경로. 논블로킹 애플리케이션에는 AsyncCodex를 사용하세요. 같은 이벤트 루프에서 Codex와 AsyncCodex 인스턴스를 혼용하지 마세요:

from openai_codex import AsyncCodex
import asyncio

async def main():
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="codex-1")
        result = await thread.run("Refactor this module for clarity.")
        print(result.final_response)

asyncio.run(main())

스트리밍. 장시간 실행되는 에이전트 턴에는 run_streamed()가 증분 이벤트를 반환합니다. event.type을 폴링하세요 — 부분 텍스트는 "turn.delta", 최종 사용량 요약은 "turn.completed"입니다:

streamed = await thread.run_streamed("Diagnose the CI failure")
async for event in streamed.events:
    if event.type == "turn.delta":
        print(event.content, end="", flush=True)
    elif event.type == "turn.completed":
        print("\nUsage:", event.usage)

아래 엔드투엔드 스니펫은 새 venv를 만들고 SDK를 설치한 뒤 스모크 테스트를 실행합니다. 네트워크 제약으로 인해 기사 생성 시점에 라이브 API에 대해 실제로 실행되지는 않았지만, 설치 경로와 임포트는 v0.1.0b2 기준으로 정확합니다:

import os
import subprocess
import sys
from pathlib import Path

if not os.getenv("CODEX_DEMO_VENV"):
    venv = Path(".codex-demo-venv")
    subprocess.check_call([sys.executable, "-m", "venv", str(venv)])
    py = venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
    subprocess.check_call([str(py), "-m", "pip", "install", "-q", "openai-codex==0.1.0b2"])
    os.execve(str(py), [str(py), __file__], {**os.environ, "CODEX_DEMO_VENV": "1"})

from openai_codex import Codex

with Codex() as codex:
    if os.getenv("OPENAI_API_KEY"):
        codex.login_api_key(os.environ["OPENAI_API_KEY"])
        print("authenticated with OPENAI_API_KEY")
    else:
        print("using existing Codex auth")

    thread = codex.thread_start()
    result = thread.run("Reply with exactly: Codex SDK OK")
    print(result.final_response)

브라우저 없이 인증하기

v0.1.0b2는 인터랙티브 데스크탑 세션부터 완전 헤드리스 CI 컨테이너까지 포괄하는 네 가지 인증 모드를 제공합니다. 퍼스트클래스 인증 지원은 Codex CLI v0.132.0과 함께 도입됐습니다 . 자동 모드 — 기존 codex login 자격 증명 재사용 — 는 추가 코드가 필요 없습니다. CI나 헤드리스 컨테이너에서는 API 키 모드가 가장 직접적이며 브라우저가 필요하지 않습니다.

완전 자동화된 컨테이너 배포에서는 CODEX_AUTH_JSON 환경 변수를 설정하고 프로그래밍 방식의 로그인 호출을 완전히 생략할 수 있습니다 . SDK가 시작 시 이를 읽습니다 — 시크릿을 환경 변수로 주입하는 방식이 이미 표준화된 Kubernetes나 Docker 파이프라인에 가장 깔끔한 방법입니다.

제한된 환경에서는 디바이스 코드 플로우가 유용합니다: login.verification_url과 login.user_code가 표준 출력에 출력되면, 사람이 해당 URL을 방문해 코드를 입력하고, login.wait()가 플로우 완료까지 블로킹됩니다. 확인이 완료되면 세션이 로컬에 저장되어 이후 실행 시 플로우를 반복하지 않고 재사용됩니다.

주의할 점과 시도해 볼 패턴

이 베타 버전을 기반으로 개발하기 전에 알아두어야 할 실용적인 주의사항입니다:

• 버전을 고정하세요. API 표면은 베타 릴리스 간에 안정성 보장 없이 변경됩니다. pip install openai-codex==0.1.0b2를 사용하고, 버전을 올리기 전에 Codex changelog를 확인하세요 . 업그레이드는 격리된 환경에서 테스트하세요.
• 기본 샌드박스는 FULL_ACCESS입니다. 프롬프트 텍스트를 완전히 신뢰할 수 없는 경우 — 사용자 제공 입력, 외부 데이터, PR 코멘트 본문 등 — Sandbox.READ_ONLY 또는 Sandbox.WORKSPACE_WRITE를 명시적으로 설정하세요. Codex CLI v0.135.0 changelog 에서는 이를 보안 고려사항으로 표시하고 있습니다.
• 세션 파일이 누적됩니다. 모든 스레드는 ~/.codex/sessions에 저장됩니다. 짧은 테스트 세션을 많이 실행할 경우 해당 디렉터리를 수동으로 정리하세요 — 내장된 TTL이나 자동 정리 기능은 없습니다.
• 장시간 실행 시 스트리밍 동작은 문서화되어 있지 않습니다. 몇 분을 초과하는 에이전트 작업에서 run_streamed()의 동작은 이 베타 버전에서 문서화된 보장이 없습니다. 장기 실행 파이프라인에서는 실험적인 기능으로 취급하세요.
• 가격 및 요청 한도는 SDK에 명시되어 있지 않습니다. 이는 Codex 구독 티어에서 상속됩니다 — SDK README 대신 계정 대시보드를 확인하세요.

다음으로 시도해볼 것: CodexConfig를 사용하여 사용자 지정 작업 디렉터리와 모델을 설정하세요:

from openai_codex import Codex, CodexConfig, Sandbox

config = CodexConfig(
    model="codex-1",
    working_directory="/path/to/project",
    env={"MY_VAR": "value"},
)
with Codex(config=config) as codex:
    thread = codex.thread_start(sandbox=Sandbox.WORKSPACE_WRITE)
    result = thread.run("Audit the test coverage.")
    print(result.final_response)

구조화된 출력의 경우 run()과 output_schema=MyModel.model_json_schema()를 통한 Pydantic v2 스키마를 연결하고, MyModel.model_validate_json(result.final_response)으로 검증하세요. run_streamed()를 FastAPI SSE 엔드포인트에 연결하는 것은 실시간 에이전트 출력을 제공하는 개발자용 도구의 자연스러운 다음 단계입니다. 전체 API 표면은 GitHub의 SDK 소스와 PyPI 릴리스 페이지에 문서화되어 있습니다.

자주 묻는 질문

pip install openai-codex를 실행하면 Codex CLI 바이너리도 함께 설치되나요?

아닙니다. 휠은 openai-codex-cli-bin을 의존성으로 선언하지만 바이너리 자체를 포함하지는 않습니다. 대부분의 환경에서는 의존성이 자동으로 해결되어 바이너리가 설치됩니다. 부트스트랩을 명시적으로 제어해야 하는 컨테이너나 노트북에서는 다른 SDK 호출 전에 Codex.install(version='rust-v0.132.0')을 호출하세요. 바이너리가 없으면 대부분의 SDK 메서드는 즉시 명확한 오류를 발생시킵니다.

ChatGPT 계정 대신 일반 OpenAI API 키를 사용할 수 있나요?

네. codex.login_api_key('sk-...')는 일반 OpenAI API 키를 허용하며, 브라우저 상호작용 없이 헤드리스 CI에서 작동합니다. OPENAI_API_KEY를 환경 변수로 설정하고 시작 코드에서 codex.login_api_key(os.environ["OPENAI_API_KEY"])를 호출하세요. 이 방식이 자동화 파이프라인과 컨테이너 배포에 권장되는 방법입니다.

Sandbox.READ_ONLY와 Sandbox.WORKSPACE_WRITE의 차이는 무엇인가요?

Sandbox.READ_ONLY는 에이전트가 파일을 읽을 수 있지만 쓰거나 수정할 수 없습니다 — 쓰기 제로를 보장해야 하는 분석, 코드 리뷰, 질의응답 작업에 적합합니다. Sandbox.WORKSPACE_WRITE는 현재 작업 디렉터리 내에서만 쓰기를 허용하며, 대부분의 코딩 및 리팩터링 작업을 커버합니다. Sandbox.FULL_ACCESS는 기본값이며 제한이 없습니다 — 입력 프롬프트를 완전히 제어하고 신뢰할 때만 사용하세요.

이전 Python 세션에서 스레드를 이어가려면 어떻게 해야 하나요?

첫 번째 턴 이후 result.thread_id(문자열)를 데이터베이스, 파일 또는 환경 변수에 저장하세요. 새 Python 세션에서 평소대로 Codex()를 인스턴스화한 다음 codex.resume_thread(thread_id)를 호출하여 대화를 다시 불러오세요. 세션은 ~/.codex/sessions에 디스크로 저장되며 Python을 재시작해도 유지됩니다. 자동 정리 기능이 없으므로, 짧은 테스트 스레드를 많이 실행한다면 해당 디렉터리를 주기적으로 정리하세요.

openai-codex v0.1.0b2는 프로덕션에 사용하기에 충분히 안정적인가요?

PyPI 릴리스 페이지 에 명시된 대로, 베타 버전 간 API 안정성 보장이 없는 공개 베타입니다. 올바른 접근 방식: openai-codex==0.1.0b2로 고정하고, Codex 릴리스 로그를 모니터링하며, 배포 전 버전 업그레이드를 격리된 환경에서 테스트하세요. 호환성을 깨는 API 변경을 허용할 수 없는 워크로드의 경우 1.0 릴리스를 기다리세요.

지금 당장 활용하는 법

v0.1.0b2에서 즉시 실행할 수 있는 두 가지가 있습니다. 첫째, Codex SDK에 원시 권한 문자열을 전달하는 기존 코드가 있다면 이를 명명된 Sandbox 프리셋으로 교체하세요 — 스레드당 한 줄 변경으로 파일시스템 영향 범위를 크게 줄이고 코드 리뷰에서 의도를 명확히 할 수 있습니다. 둘째, CI에서 Codex를 실행 중이라면 login_api_key() 방식이 브라우저 인증 우회 방법을 없애고 파이프라인의 다른 API 키 처리 방식과 인증 모델을 일치시킵니다.

버전 관리 체계가 이제 분리되었습니다: pyproject.toml의 소스에는 version = "0.0.0-dev"가 포함되며, 게시 버전은 릴리스 시점에 python-v* git 태그에서 주입됩니다 . 이는 각 버전 업그레이드마다 소스 트리 커밋 없이 베타 릴리스를 더 빠르게 배포할 수 있음을 의미합니다. 1.0의 모습을 파악하려면 v0.1.0b2 릴리스 노트와 공식 SDK 문서를 추적하세요 — 릴리스 주기는 여기서 가속화될 가능성이 높습니다.

최종 업데이트: 2026-05-31. PyPI의 openai-codex v0.1.0b2 및 해당 날짜에 검토한 Codex CLI v0.135.0 changelog를 기반으로 합니다.