Codex SDK

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

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

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

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

CI 작업을 비롯한 코딩 작업을 자동화하려면 Codex SDK를 사용하세요. 인증, 대화 기록, 승인 및 스트리밍되는 에이전트 이벤트를 처리하는 맞춤형 클라이언트를 구축하려면 Codex app server를 사용하세요.

codex mcp-server 명령과 독립 실행형 codex-mcp-server 바이너리는 제거되었습니다. 기존 연동에는 Codex 앱 서버를 사용하세요.

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

TypeScript 라이브러리

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

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

설치

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

npm install @openai/codex-sdk

사용법

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

import { Codex } from "@openai/codex-sdk";

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, {
  sandboxMode: "workspace-write",
});
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

통합 기능에서 생성한 스레드를 식별하려면 스레드를 생성할 때 threadSource를 설정하세요. 예를 들어 codex.startThread({ threadSource: "ci" })는 스레드의 출처를 ci로 표시합니다. 스레드를 재개해도 원래 출처는 유지됩니다.

구성 재정의

config를 전달해 구조화된 Codex 구성을 설정하세요. 점으로 구분된 경로로 표현할 수 없는 키는 configOverrides를 사용해 원시 TOML 문자열을 별도의 --config 인수로 전달하세요.

const codex = new Codex({
  config: { default_permissions: "audit" },
  configOverrides: [
    'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',
  ],
});

원시 재정의 값은 구조화된 config보다 우선합니다. SDK는 baseUrl 같은 관리 설정과 스레드별 옵션을 나중에 적용하므로 이 설정과 옵션은 구조화된 구성과 원시 재정의보다 우선합니다. 이러한 재정의는 Codex 구성 파일을 변경하지 않습니다.

자세한 내용은 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을 사용하면 최신 안정 릴리스가 설치됩니다. 더 새로운 프리릴리스 빌드를 사용하려면 pip install --pre openai-codex을 사용하세요.

사용법

Codex를 시작하고 스레드를 만든 다음 프롬프트를 실행하세요. 예제에서는 GPT-6.1 Sol을 사용하며, 로그인한 계정에서 이 모델을 사용할 수 있어야 합니다. 그렇지 않으면 model을 생략하여 구성된 기본 모델을 사용하세요. 플랜별 GPT-6.1 Sol 사용 가능 여부를 참조하세요.

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-6.1-sol",
        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-6.1-sol")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

다른 시스템의 콘텐츠 전달

도구, 애플리케이션 또는 다른 에이전트가 콘텐츠를 제공하는 경우, ExternalMessage를 thread.run() 또는 thread.turn()의 전체 입력으로 전달하세요. 예를 들어 ExternalMessage(tool_name="issue_tracker", content=issue_body)는 이슈 설명을 제공한 도구를 식별합니다. Codex는 이 설명을 도구 출력으로 취급하며, 사용자 및 개발자 지침보다 낮은 우선순위를 적용합니다. 이 메시지로 턴을 시작하거나 진행 중인 일반 턴에 참여할 수 있습니다.

기록을 불러오지 않고 스레드 재개

include_turns=False를 codex.thread_resume() 또는 codex.thread_fork()에 전달하면 이전 턴을 응답에 불러오지 않습니다. 모델은 여전히 스레드의 컨텍스트를 유지합니다. 나중에 기록을 가져오려면 thread.read(include_turns=True)를 호출하세요.

Codex CLI 0.166.0 이상에서는 스레드에 저장된 모델 제공자를 사용해 스레드를 재개하세요. 제공자를 변경하는 경우 codex.thread_fork(thread_id)를 호출하여 새 제공자에서 동일한 기록을 바탕으로 계속 진행하세요.

단일 턴의 서비스 등급 설정

새로운 단일 턴의 서비스 등급을 선택하려면 turn_service_tier를 run() 또는 turn()에 전달하세요. 예를 들어 turn_service_tier="default"는 해당 턴에 표준 속도를 적용합니다. 현재 턴과 이후 턴의 등급을 변경하려면 service_tier를 전달하세요. 진행 중인 턴에 참여하면 해당 턴의 등급은 그대로 유지됩니다.

자체 Codex 실행 파일을 사용하는 경우, ExternalMessage, 재개 또는 포크 시 명시적인 include_turns 지정, turn_service_tier를 사용하려면 Codex CLI 0.151.0 이상이 필요합니다.

샌드박스 프리셋

스레드를 생성하거나 이후 턴의 파일 시스템 액세스를 변경할 때 동일한 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 저장소를 확인하세요.