OpenAI 공식 문서 — Codex SDK 빌더

14. Codex SDK (TS · Python)

Codex 엔진을 여러분의 코드에서 호출하기 위한 공식 SDK입니다. TypeScript와 Python(experimental)을 지원하며, 로컬 Codex App Server를 JSON-RPC로 제어해 CI · 내부 봇 · 평가 파이프라인 · 커스텀 에이전트에 임베드할 수 있습니다. 비대화형 codex exec --json·구조화 출력, Agents SDK 통합, MCP 서버로 노출하기까지 한 페이지로 정리합니다.

이 페이지에서 배우는 것

• 1Codex SDK는 무엇이고, CLI/App과 어떻게 다른가
• 2TypeScript SDK 설치·초기화·thread 사용법
• 3Python SDK(동기 + AsyncCodex) 기본 사용
• 4codex exec --json --output-schema 비대화형 모드 + 구조화 출력
• 5Agents SDK · MCP 서버로 Codex를 다른 시스템에 노출하기
• 6App Server JSON-RPC 프로토콜 — SDK 내부에서 어떤 일이 일어나는가

Codex SDK란? — CLI · App과의 차이

Codex SDK는 코드에서 Codex를 호출하기 위한 공식 라이브러리입니다. 같은 Codex 엔진을 사용하지만 인터페이스가 다릅니다.

"Codex를 호출하는 또 다른 코드"가 필요하다면 SDK가 답입니다 — subprocess.run(["codex", "exec", ...])보다 타입 안전하고, thread/turn 라이프사이클을 라이브러리가 관리하며, 스트리밍·이벤트도 일급으로 받습니다.

TypeScript SDK (Node.js 18+)

설치

npm i @openai/codex-sdk
# 또는
pnpm add @openai/codex-sdk

최소 예제 — thread 시작 · 실행 · 결과 받기

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

const codex = new Codex({
  // 인증: 기본은 ~/.codex/auth.json. apiKey도 가능.
  // apiKey: process.env.OPENAI_API_KEY,
});

const thread = await codex.startThread({
  cwd: process.cwd(),                 // 작업 디렉터리
  approvalPolicy: "never",            // 무인 실행
  sandbox: "workspace-write",         // workspace-write | read-only | danger-full-access
  model: "gpt-5-codex",
});

const result = await thread.run({
  prompt: "Find all TODO comments in src/ and group them by feature area.",
});

console.log(result.finalMessage);     // 모델의 최종 응답
for (const item of result.items) {    // tool calls, file changes, etc.
  console.log(item.type, item.summary);
}

세션 재개 — resumeThread

// 이전 thread를 ID로 재개
const thread2 = await codex.resumeThread(savedThreadId);
const result2 = await thread2.run({ prompt: "Now also update the README." });

스트리밍 이벤트

const stream = thread.runStream({ prompt: "Refactor utils.ts" });
for await (const event of stream) {
  if (event.type === "assistant_message_delta") process.stdout.write(event.text);
  if (event.type === "tool_call") console.log("tool:", event.tool, event.args);
  if (event.type === "file_change") console.log("changed:", event.path);
  if (event.type === "done") break;
}

Python SDK (3.10+, experimental)

Python SDK는 동기 Codex와 비동기 AsyncCodex 두 가지 클라이언트를 제공합니다.

설치

pip install openai-codex
# 또는
uv add openai-codex

동기 예제

from openai_codex import Codex

codex = Codex()  # 기본 인증: ~/.codex/auth.json

thread = codex.thread_start(
    cwd=".",
    approval_policy="never",
    sandbox="workspace-write",
    model="gpt-5-codex",
)

result = thread.run(prompt="Add a unit test for the new feature in auth.py")
print(result.final_message)

비동기 예제 (FastAPI 등에서)

import asyncio
from openai_codex import AsyncCodex

async def main():
    codex = AsyncCodex()
    thread = await codex.thread_start(cwd=".", approval_policy="never")
    result = await thread.run(prompt="Audit DB queries for N+1 patterns")
    print(result.final_message)

asyncio.run(main())

codex exec 비대화형 모드 — SDK 없이 쉘에서

SDK 없이도 비대화형으로 Codex를 부를 수 있습니다. CI 셸 스크립트나 Makefile 한 줄에서 쓸 때 유용합니다.

# 기본 비대화형
codex exec "Update CHANGELOG.md with the recent commits"

# JSON 출력 + 구조화 스키마
codex exec --json --output-schema=schema.json   "Review src/ for security issues. Return a list of {file, line, severity, fix}."

# 마지막 메시지만 파일로
codex exec --output-last-message=result.md "Summarize today's changes"

--output-schema로 JSON Schema를 주면 모델 응답이 그 스키마를 따르도록 강제됩니다. 후속 시스템이 파싱하기 좋습니다.

Agents SDK · MCP 서버로 노출하기

Codex 자신을 다른 AI 에이전트가 호출할 수 있는 도구로 노출할 수도 있습니다 — Codex SDK를 OpenAI Agents SDK 안에서 도구로 등록하거나, codex mcp-server로 stdio MCP 서버로 띄워 Claude/Cursor/다른 Codex가 그것을 도구로 사용하게 합니다.

# Codex 자신을 MCP 서버로 띄우기 (다른 에이전트가 도구로 호출)
codex mcp-server

# Agents SDK에서 Codex를 tool로 등록 (TypeScript 예)
import { Codex } from "@openai/codex-sdk";
import { Agent, tool } from "@openai/agents";

const codex = new Codex();
const codexTool = tool({
  name: "codex_run",
  description: "Run a Codex coding task end-to-end",
  parameters: { prompt: z.string() },
  execute: async ({ prompt }) => {
    const t = await codex.startThread({ approvalPolicy: "never" });
    const r = await t.run({ prompt });
    return r.finalMessage;
  },
});

const agent = new Agent({ tools: [codexTool] });

App Server (JSON-RPC) — SDK 내부에서 무슨 일이 일어나는가

모든 Codex 클라이언트(App·IDE·CLI·SDK)는 같은 App Server와 통신합니다. 프로토콜은 JSON-RPC 2.0이며 기본 transport는 stdio, 옵션으로 WebSocket(experimental, capability-token / signed-bearer-token 인증)과 HTTP healthcheck(/readyz, /healthz)를 제공합니다.

대부분의 사용자는 SDK만으로 충분합니다. App Server는 자체 클라이언트를 만들거나 통합 디버깅이 필요할 때만 직접 다룹니다. 자세한 메서드 목록은 공식 App Server 문서를 참고하세요.

실전 패턴

• ✓CI 자동 리뷰 — PR 이벤트에서 codex exec --json으로 변경 diff를 분석하고 리뷰 코멘트를 게시 (자세히는 16. Integrations의 GitHub Action 예시)
• ✓평가 파이프라인 — 모델·프롬프트 A/B 테스트에 SDK로 동일한 task를 여러 thread로 병렬 실행하고 결과 비교
• ✓슬랙 봇 — 슬랙 메시지를 받아 AsyncCodex.thread_start()로 작업 위임, 결과를 다시 슬랙으로 회신 (또는 공식 Slack 통합 사용)
• ✓주기 자동화 — Codex 앱의 Automations 대신 외부 스케줄러(GitHub Actions cron, Kubernetes Job)에서 SDK로 호출해 결과를 자체 시스템에 저장

한계점