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 App Server를 사용하세요.
베타 액세스 권한이 있고 리포지터리나 변경 사항을 스캔해 발견된 보안 이슈와 검사 범위를 구조화된 형식으로 확인해야 한다면 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로 표시됩니다. 스레드를 재개해도 처음 지정한 출처는 유지됩니다.
설정 재정의
Codex 설정을 구조화된 형식으로 지정하려면 config를 전달하세요. 점으로 구분된 경로로 표현할 수 없는 키는 configOverrides를 사용해 TOML 문자열을 각각 별도의 --config 인수로 전달하세요.
const codex = new Codex({
config: { default_permissions: "audit" },
configOverrides: [
'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',
],
});TOML 문자열로 재정의한 값은 구조화된 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 실행 파일을 직접 지정하는 경우 다음 기능을 사용하려면 Codex CLI 0.151.0 이상이 필요합니다. ExternalMessage 사용, 스레드 재개 또는 포크 시 include_turns 명시, turn_service_tier 지정이 이에 해당합니다.
샌드박스 프리셋
스레드를 만들 때와 이후 턴의 파일 시스템 접근 권한을 변경할 때 모두 같은 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: 파일을 읽을 수 있으며, 워크스페이스와 쓰기를 허용하도록 설정한 루트 디렉터리 안에서 파일을 쓸 수 있습니다.Sandbox.full_access: 파일 시스템 접근 제한 없이 실행합니다.
sandbox=를 생략하면 App Server에 설정된 기본값이 적용됩니다. run(...) 또는 turn(...)에 전달한 샌드박스 설정은 해당 턴과 같은 스레드의 이후 턴에 적용됩니다.
자세한 내용은 Python 리포지터리를 참고하세요.