OpenAI

OpenAI

OpenAI 모델을 Docker Agent에서 사용하는 방법을 설명해요. Thinking 예산, 커스텀 엔드포인트, WebSocket 전송까지 다룬답니다.

출처: 문서

본문

설정

# API 키 설정
export OPENAI_API_KEY="sk-..."

팁 API 키가 없나요? ChatGPT Plus/Pro/Business 구독을 chatgpt 프로바이더로 대신 쓸 수 있어요. docker agent setup에서 한 번 로그인(chatgpt 선택)하면 돼요.

구성

인라인

agents:
  root:
    model: openai/gpt-5.6

네임드 모델

models:
  gpt:
    provider: openai
    model: gpt-5.6
    max_tokens: 4000

사용 가능한 모델

모델 용도
gpt-5.6 gpt-5.6-sol의 별칭, 플래그십 모델 추적
gpt-5.6-sol 프론티어 모델, 가장 강력, 복잡한 추론
gpt-5.6-terra 일상 작업의 주력; -mini 티어의 후속
gpt-5.6-luna 대량 처리, 비용 효율적; -nano 티어의 후속
gpt-5 이전 세대 플래그십
gpt-5-mini 이전 세대 빠르고 비용 효율적인 모델
gpt-4o 멀티모달, 균형 잡힌 성능
gpt-4o-mini 가장 저렴, 간단한 작업에 빠름

GPT-5.6부터 OpenAI는 -mini/-nano 크기 티어를 -terra/-luna로 이름을 바꿨어요(-sol은 이전에 접미사가 없던 프론티어 티어를 뜻해요).

더 많은 모델 이름은 modelnames.ai 또는 공식 OpenAI 문서에서 찾아보세요.

Thinking 예산

OpenAI 추론 모델(o-시리즈, gpt-5, gpt-5-mini, gpt-5.6 계열)은 reasoning_effort API 파라미터로 확장 생각을 지원해요. thinking_budget으로 노력 수준을 제어하세요:

models:
  gpt-thinker:
    provider: openai
    model: gpt-5.6
    thinking_budget: high   # none | minimal | low | medium | high | xhigh | max

노력 수준:

수준 설명
none 추론 없음. gpt-5.6+에서는 실제 API 값으로 그대로 전송되고, 이전 모델에서는 로컬 thinking_budget만 비활성화(API 자체 기본값은 여전히 적용).
minimal 가장 빠름, 가장 가벼운 추론 패스. gpt-5.6+에서는 받아들여지지 않음(API에서 제거됨).
low 단순 작업을 위한 빠른 추론.
medium 균형 잡힌 기본값.
high 더 철저함, 복잡한 작업에 권장.
xhigh 거의 최대 노력, 느리지만 가장 정확. gpt-5.2+ 필요.
max 최대 노력. gpt-5.6+(Sol/Terra/Luna) 필요.

토큰 수, adaptive, adaptive/는 요청 시점에 구성 오류로 거부돼요. 이전 모델(o1, o3-mini)은 low/medium/high만 받고, xhigh는 gpt-5.2+가, none과 max는 gpt-5.6+가 필요해요. minimal은 gpt-5.6+에서 받아들여지지 않아요.

경고 숨겨진 추론 토큰 OpenAI 추론 모델은 항상 max_tokens에 포함되는 숨겨진 추론 토큰을 생성해요 — 이전 모델에서 thinking_budget: none일 때조차요. Docker Agent는 내부 저노력 호출의 출력 토큰 하한을 자동으로 올려서, 추론이 보이는 텍스트 출력을 굶기지 않게 해요.

전 프로바이더 개요는 Thinking / Reasoning 가이드를 참고하세요.

팁 커스텀 엔드포인트 프록시와 OpenAI 호환 서비스에는 base_url을 사용하세요. 전체 설정은 Custom Providers 문서를 참고하세요.

커스텀 엔드포인트

OpenAI 호환 API에 연결하려면 base_url을 쓰세요:

models:
  custom:
    provider: openai
    model: gpt-5-mini
    base_url: https://your-proxy.example.com/v1

WebSocket 전송

OpenAI Responses API 모델(gpt-4.1+, o-시리즈, gpt-5)에서는 기본 SSE(Server-Sent Events) 대신 WebSocket 스트리밍을 쓸 수 있어요:

models:
  fast-gpt:
    provider: openai
    model: gpt-4.1
    provider_opts:
      transport: websocket  # SSE 대신 WebSocket 사용

장점

  • 도구 호출이 20개 이상인 워크플로에서 약 40% 더 빠름
  • 지속 연결로 턴당 오버헤드 감소
  • 연결 상태의 서버 측 캐싱
  • WebSocket 실패 시 SSE로 자동 폴백

요구사항

  • Responses API 모델에서만 동작: gpt-4.1+, o1, o3, o4, gpt-5
  • --models-gateway 플래그와는 호환되지 않음(게이트웨이가 설정되면 자동으로 SSE로 폴백)
  • OPENAI_API_KEY 환경 변수 필요

예시

examples/websocket_transport.yaml에서 완전한 예시를 확인하세요.

더 알아보기 (Learn more)