Codex CLI

프로바이더 인스턴스 (Provider Instance)

기본 프로바이더 인스턴스를 임포트해요:

import {
  createCodexAppServer,
  type Session,
} from 'ai-sdk-provider-codex-app-server';

let session: Session;

const provider = createCodexAppServer({
  defaultSettings: {
    onSessionCreated: s => {
      session = s;
    },
  },
});

실행 중 주입 (Mid-Execution Injection)

이 프로바이더의 핵심 기능은 에이전트가 활발히 작업하는 동안 메시지를 주입할 수 있다는 거예요:

import {
  createCodexAppServer,
  type Session,
} from 'ai-sdk-provider-codex-app-server';
import { streamText } from 'ai';

let session: Session;

const provider = createCodexAppServer({
  defaultSettings: {
    onSessionCreated: s => {
      session = s;
    },
  },
});

const model = provider('gpt-5.1-codex-max');

// 스트리밍 시작
const resultPromise = streamText({
  model,
  prompt: 'Write a calculator in Python',
});

// 실행 중 추가 지시 주입
setTimeout(async () => {
  await session.injectMessage('Also add a square root function');
}, 2000);

const result = await resultPromise;
console.log(await result.text);

세션 API (Session API)

세션 객체는 활성 턴에 대한 제어를 제공해요:

interface Session {
  readonly threadId: string;
  readonly turnId: string | null;

  // 실행 중 메시지 주입
  injectMessage(content: string | UserInput[]): Promise<void>;

  // 현재 턴 중단
  interrupt(): Promise<void>;

  // 턴이 활성 상태인지 확인
  isActive(): boolean;
}

모델 탐색 (Model Discovery)

사용 가능한 모델과 그 기능을 탐색할 수 있어요:

import { listModels } from 'ai-sdk-provider-codex-app-server';

const { models, defaultModel } = await listModels();

for (const model of models) {
  console.log(`${model.id}: ${model.description}`);
  const efforts = model.supportedReasoningEfforts.map(e => e.reasoningEffort);
  console.log(`  Reasoning: ${efforts.join(', ')}`);
}

설정 (Settings)

interface CodexAppServerSettings {
  codexPath?: string; // codex 바이너리 경로
  cwd?: string; // 작업 디렉토리
  approvalMode?: 'never' | 'on-request' | 'on-failure' | 'untrusted';
  sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
  reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
  threadMode?: 'persistent' | 'stateless';
  mcpServers?: Record<string, McpServerConfig>;
  verbose?: boolean;
  logger?: Logger | false;
  onSessionCreated?: (session: Session) => void;
  env?: Record<string, string>;
  baseInstructions?: string;
  resume?: string; // 이어갈 스레드 ID
}

스레드 모드 (Thread Modes)

• persistent (기본값): 여러 호출에 걸쳐 같은 스레드를 재사용해 컨텍스트를 유지해요
• stateless: 호출마다 새 스레드를 만들어요

const model = provider('gpt-5.1-codex-max', {
  threadMode: 'stateless', // 호출마다 새 스레드
});

호출별 오버라이드 (Per-Call Overrides)

providerOptions를 사용해 호출별로 설정을 오버라이드할 수 있어요:

const result = await streamText({
  model,
  prompt: 'Analyze this code',
  providerOptions: {
    'codex-app-server': {
      reasoningEffort: 'high',
      threadMode: 'stateless',
    },
  },
});

모델 기능 (Model Capabilities)

Codex CLI 프로바이더와 비교 (Comparison with Codex CLI Provider)

단순한 1회성 작업에는 Codex CLI 프로바이더를 사용하세요. 인간 개입 워크플로우(human-in-the-loop), 실시간 코스 수정, 협업 코딩이 필요할 때는 Codex App Server 프로바이더를 사용하세요.

요구 사항 (Requirements)

• Node.js 22 이상
• 전역에 설치된 Codex CLI (v0.60.0+ 권장)
• ChatGPT Plus/Pro 구독 또는 OpenAI API 키

자세한 내용은 프로바이더 문서를 참고하세요.

더 알아보기 (Learn more)

• 커스텀 프로바이더 작성하기

전체 사이트맵