Codex SDK는 사용자가 Codex를 프로그램적으로 제어할 수 있도록 설계된 도구이다. 이는 CI/CD 파이프라인에 Codex를 통합하거나, 복잡한 엔지니어링 작업을 수행하는 에이전트를 구축하거나, 내부 도구 및 애플리케이션 내에 Codex를 연동하는 데 활용될 수 있다.

이 SDK는 두 가지 주요 라이브러리로 제공된다: TypeScript 라이브러리와 Python 라이브러리.

TypeScript 라이브러리
이 라이브러리는 Node.js 18 이상 환경에서 서버 사이드에서 Codex를 제어하는 데 사용된다. npm install @openai/codex-sdk 명령어를 통해 설치할 수 있다. 사용자는 Codex 인스턴스를 생성하고, codex.startThread()를 호출하여 새로운 thread를 시작할 수 있다. 이후 await thread.run("Prompt") 메서드를 사용하여 Codex와 상호작용하며 결과(result)를 얻는다. 동일한 thread에서 run()을 다시 호출하여 대화를 이어가거나, 기존 thread의 threadId를 사용하여 codex.resumeThread(threadId)로 중단된 대화를 재개할 수 있다.

Python 라이브러리
Python 3.10 이상을 필요로 하며, pip install openai-codex를 통해 설치된다. 이 라이브러리는 JSON-RPC를 통해 로컬 Codex app-server를 제어하며, 빌드에는 고정된 Codex CLI runtime이 포함된다. with Codex() as codex:와 같은 context manager를 사용하여 Codex 인스턴스를 초기화한다. $codex.thread_start(model="gpt-5.4", sandbox=Sandbox.workspace_write)$ 메서드로 thread를 시작하며, 이때 model 지정 및 sandbox 설정이 가능하다. thread.run("Prompt")를 통해 프롬프트를 실행하고, result.final_response로 최종 응답을 얻을 수 있다. 비동기 애플리케이션의 경우 AsyncCodex를 사용할 수 있으며, async with AsyncCodex() as codex: 형태로 활용된다.

Core Methodology: Sandbox Presets
Codex SDK의 핵심적인 기능 중 하나는 Sandbox 프리셋을 통해 파일시스템 접근 권한을 세밀하게 제어하는 것이다. thread_start 시점에 sandbox 파라미터를 명시하거나, run(...) 또는 turn(...) 메서드 호출 시점에 sandbox를 지정하여 해당 turn 및 이후 turn에 적용되는 파일시스템 접근 권한을 설정할 수 있다. 사용 가능한 Sandbox 프리셋은 다음과 같다:

• Sandbox.read_only: 파일 읽기만 허용하며 쓰기 작업은 불가능하다.
• Sandbox.workspace_write: 파일을 읽고 workspace 및 구성된 writable roots 내에 파일을 쓰는 것을 허용한다.
• Sandbox.full_access: 파일시스템 접근 제한 없이 모든 작업을 허용한다.

sandbox 파라미터가 생략될 경우, app-server에 구성된 기본 설정이 사용된다.