ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

Codex SDK

로컬 Codex 에이전트를 프로그래밍 방식으로 제어

Codex CLI, IDE 확장 프로그램 또는 Codex cloud를 통해 Codex를 사용하는 경우 프로그래밍 방식으로도 제어할 수 있습니다.

다음과 같은 경우 SDK를 사용하세요.

  • CI/CD 파이프라인의 일부로 Codex 제어
  • Codex와 상호작용하여 복잡한 엔지니어링 작업을 수행할 수 있는 자체 에이전트 생성
  • 자체 내부 도구 및 워크플로에 Codex 도입
  • 자체 애플리케이션에 Codex 통합

코딩 중심의 Codex 스레드에는 Codex SDK를 사용하세요. Codex가 더 광범위하게 오케스트레이션된 워크플로 내의 전문 에이전트 중 하나라면 Codex CLI를 MCP 서버로 실행하고 Agents SDK로 오케스트레이션하세요.

베타 액세스 권한이 있고 구조화된 보안 결과와 커버리지를 포함하는 저장소 또는 변경 사항 검사가 필요하다면 Codex Security TypeScript SDK를 사용하세요.

TypeScript 라이브러리

TypeScript 라이브러리를 사용하면 애플리케이션에서 로컬 Codex 스레드를 시작하고, 계속 진행하고, 재개할 수 있습니다.

이 라이브러리는 서버 측에서 사용하세요. Node.js 18 이상이 필요합니다.

설치

시작하려면 npm을 사용하여 Codex SDK를 설치하세요.

npm install @openai/codex-sdk

사용법

Codex로 스레드를 시작하고 프롬프트를 사용해 실행하세요.



const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);

동일한 스레드에서 계속하려면 run()을 다시 호출하고, 이전 스레드를 재개하려면 스레드 ID를 제공하세요.

// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

자세한 내용은 TypeScript 저장소를 확인하세요.

Python 라이브러리

Python SDK는 JSON-RPC를 통해 로컬 Codex app-server를 제어합니다. Python 3.10 이상이 필요합니다. 배포된 SDK 빌드에는 버전이 고정된 Codex CLI 런타임 종속성이 포함됩니다.

설치

SDK를 설치하려면 다음을 실행하세요.

pip install openai-codex

배포된 SDK 빌드는 버전이 고정된 런타임을 자동으로 사용합니다. 특정 로컬 Codex 실행 파일을 의도적으로 사용하려는 경우에만 CodexConfig(codex_bin=...)을 전달하세요.

Python SDK가 베타인 동안에는 pip install openai-codex을 사용하면 배포된 최신 베타 빌드가 선택됩니다. 안정적인 SDK 릴리스가 제공된 후에는 pip install --pre openai-codex을 사용하여 최신 프리릴리스 빌드를 선택하세요.

사용법

Codex를 시작하고 스레드를 생성한 다음 프롬프트를 실행하세요.

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.6-terra",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

애플리케이션이 이미 비동기 방식인 경우 AsyncCodex을 사용하세요.

import asyncio

from openai_codex import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.6-terra")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

샌드박스 프리셋

스레드를 생성하거나 이후 턴의 파일 시스템 액세스를 변경할 때 동일한 Sandbox 프리셋을 사용하세요.

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

사용 가능한 프리셋은 다음과 같습니다.

  • Sandbox.read_only: 쓰기를 허용하지 않고 파일을 읽습니다.
  • Sandbox.workspace_write: 파일을 읽고 workspace 및 구성된 쓰기 가능 루트 내부에 씁니다.
  • Sandbox.full_access: 파일 시스템 액세스 제한 없이 실행합니다.

sandbox=을 생략하면 app-server는 구성된 기본값을 사용합니다. run(...) 또는 turn(...)에 전달된 샌드박스는 해당 턴과 스레드의 이후 턴에 적용됩니다.

자세한 내용은 Python 저장소를 확인하세요.