메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenAI는 GPT 모델용 개발자 API를 제공하며, Codex는 OpenAI의 Codex 클라이언트를 통해 ChatGPT 플랜 코딩 에이전트로도 사용할 수 있습니다. OpenClaw는 구성이 예측 가능하게 유지되도록 이러한 표면을 분리합니다. OpenClaw는 openai/*를 표준 OpenAI 모델 경로로 사용합니다. OpenAI 모델의 임베디드 에이전트 턴은 기본적으로 네이티브 Codex 앱 서버 런타임을 통해 실행됩니다. 직접 OpenAI API 키 인증은 이미지, 임베딩, 음성, 실시간과 같은 비에이전트 OpenAI 표면에서 계속 사용할 수 있습니다.
  • 에이전트 모델 - Codex 런타임을 통한 openai/* 모델입니다. ChatGPT/Codex 구독 사용을 위해 Codex 인증으로 로그인하거나, 의도적으로 API 키 인증을 사용하려는 경우 Codex 호환 OpenAI API 키 백업을 구성하세요.
  • 비에이전트 OpenAI API - OPENAI_API_KEY 또는 OpenAI API 키 온보딩을 통해 사용량 기반 과금으로 OpenAI Platform에 직접 액세스합니다.
  • 레거시 구성 - openai-codex/* 모델 참조는 openclaw doctor --fix에 의해 openai/*와 Codex 런타임으로 복구됩니다.
OpenAI는 OpenClaw 같은 외부 도구와 워크플로에서 구독 OAuth 사용을 명시적으로 지원합니다. 공급자, 모델, 런타임, 채널은 별도의 계층입니다. 이러한 레이블이 서로 혼동되고 있다면 구성을 변경하기 전에 에이전트 런타임을 읽으세요.

​
빠른 선택

목표사용참고
네이티브 Codex 런타임이 포함된 ChatGPT/Codex 구독openai/gpt-5.5기본 OpenAI 에이전트 설정입니다. Codex 인증으로 로그인하세요.
에이전트 모델에 직접 API 키 과금openai/gpt-5.5와 Codex 호환 API 키 프로필auth.order.openai를 사용해 백업을 구독 인증 뒤에 배치하세요.
명시적 PI를 통한 직접 API 키 과금openai/gpt-5.5와 공급자/모델 런타임 pi일반 openai API 키 프로필을 선택하세요.
최신 ChatGPT Instant API 별칭openai/chat-latest직접 API 키 전용입니다. 기본값이 아닌 실험용 이동 별칭입니다.
명시적 PI를 통한 ChatGPT/Codex 구독 인증openai/gpt-5.5와 공급자/모델 런타임 pi호환성 경로를 위해 openai-codex 인증 프로필을 선택하세요.
이미지 생성 또는 편집openai/gpt-image-2OPENAI_API_KEY 또는 OpenAI Codex OAuth 모두에서 작동합니다.
투명 배경 이미지openai/gpt-image-1.5outputFormat=png 또는 webp와 openai.background=transparent를 사용하세요.

​
이름 매핑

이름은 비슷하지만 서로 바꿔 쓸 수 없습니다.
표시되는 이름계층의미
openai공급자 접두사표준 OpenAI 모델 경로입니다. 에이전트 턴은 Codex 런타임을 사용합니다.
openai-codex레거시 인증/프로필 접두사이전 OpenAI Codex OAuth/구독 프로필 네임스페이스입니다. 기존 프로필과 auth.order.openai-codex는 계속 작동합니다.
codex PluginPlugin네이티브 Codex 앱 서버 런타임과 /codex 채팅 컨트롤을 제공하는 번들 OpenClaw Plugin입니다.
공급자/모델 agentRuntime.id: codex에이전트 런타임일치하는 임베디드 턴에 대해 네이티브 Codex 앱 서버 하네스를 강제합니다.
/codex ...채팅 명령 세트대화에서 Codex 앱 서버 스레드를 바인딩/제어합니다.
runtime: "acp", agentId: "codex"ACP 세션 경로ACP/acpx를 통해 Codex를 실행하는 명시적 대체 경로입니다.
이는 구성에 의도적으로 openai/* 모델 참조가 포함되면서도 인증 프로필은 Codex 호환 자격 증명을 가리킬 수 있음을 의미합니다. 새 구성에는 auth.order.openai를 선호하세요. 기존 openai-codex:* 프로필과 auth.order.openai-codex는 계속 지원됩니다. openclaw doctor --fix는 레거시 openai-codex/* 모델 참조를 표준 OpenAI 모델 경로로 다시 씁니다.
GPT-5.5는 직접 OpenAI Platform API 키 액세스와 구독/OAuth 경로를 통해 모두 사용할 수 있습니다. ChatGPT/Codex 구독과 네이티브 Codex 실행을 함께 사용하려면 openai/gpt-5.5를 사용하세요. 이제 런타임 구성이 설정되지 않은 경우 OpenAI 에이전트 턴에 Codex 하네스가 선택됩니다. OpenAI 에이전트 모델에 직접 API 키 인증을 사용하려는 경우에만 OpenAI API 키 프로필을 사용하세요.
OpenAI 에이전트 모델 턴에는 번들 Codex 앱 서버 Plugin이 필요합니다. 명시적 PI 런타임 구성은 옵트인 호환성 경로로 계속 사용할 수 있습니다. openai-codex 인증 프로필과 함께 PI가 명시적으로 선택되면 OpenClaw는 공개 모델 참조를 openai/*로 유지하고, 내부적으로 레거시 Codex 인증 전송을 통해 PI를 라우팅합니다. 오래된 openai-codex/* 모델 참조나 명시적 런타임 구성에서 오지 않은 이전 PI 세션 고정을 복구하려면 openclaw doctor --fix를 실행하세요.

​
OpenClaw 기능 범위

OpenAI 기능OpenClaw 표면상태
채팅 / Responsesopenai/<model> 모델 공급자예
Codex 구독 모델openai/<model>과 openai-codex OAuth예
레거시 Codex 모델 참조openai-codex/<model>doctor가 openai/<model>로 복구함
Codex 앱 서버 하네스런타임 생략 또는 공급자/모델 agentRuntime.id: codex가 있는 openai/<model>예
서버 측 웹 검색네이티브 OpenAI Responses 도구웹 검색이 활성화되고 공급자가 고정되지 않은 경우 예
이미지image_generate예
동영상video_generate예
텍스트 음성 변환messages.tts.provider: "openai" / tts예
일괄 음성 텍스트 변환tools.media.audio / 미디어 이해예
스트리밍 음성 텍스트 변환Voice Call streaming.provider: "openai"예
실시간 음성Voice Call realtime.provider: "openai" / Control UI Talk예
임베딩메모리 임베딩 공급자예

​
메모리 임베딩

OpenClaw는 memory_search 인덱싱 및 쿼리 임베딩에 OpenAI 또는 OpenAI 호환 임베딩 엔드포인트를 사용할 수 있습니다. 
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}
비대칭 임베딩 레이블이 필요한 OpenAI 호환 엔드포인트의 경우 memorySearch 아래에 queryInputType과 documentInputType을 설정하세요. OpenClaw는 이를 공급자별 input_type 요청 필드로 전달합니다. 쿼리 임베딩은 queryInputType을 사용하고, 인덱싱된 메모리 청크와 일괄 인덱싱은 documentInputType을 사용합니다. 전체 예시는 메모리 구성 참조를 참고하세요.

​
시작하기

선호하는 인증 방법을 선택하고 설정 단계를 따르세요.
적합한 용도: 직접 API 액세스 및 사용량 기반 과금.
1

API 키 가져오기

OpenAI Platform 대시보드에서 API 키를 만들거나 복사하세요.
2

온보딩 실행

openclaw onboard --auth-choice openai-api-key
또는 키를 직접 전달하세요.
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

모델을 사용할 수 있는지 확인

openclaw models list --provider openai

​
경로 요약

모델 참조런타임 구성경로인증
openai/gpt-5.5생략 / 공급자/모델 agentRuntime.id: "codex"Codex 앱 서버 하네스Codex 호환 OpenAI 프로필
openai/gpt-5.4-mini생략 / 공급자/모델 agentRuntime.id: "codex"Codex 앱 서버 하네스Codex 호환 OpenAI 프로필
openai/gpt-5.5공급자/모델 agentRuntime.id: "pi"PI 임베디드 런타임openai 프로필 또는 선택한 openai-codex 프로필
openai/* 에이전트 모델은 Codex 앱 서버 하네스를 사용합니다. 에이전트 모델에 API 키 인증을 사용하려면 Codex 호환 API 키 프로필을 만들고 auth.order.openai로 순서를 지정하세요. OPENAI_API_KEY는 비에이전트 OpenAI API 표면에 대한 직접 대체 수단으로 유지됩니다. 이전 auth.order.openai-codex 항목도 계속 작동합니다.

​
구성 예시

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
OpenAI API에서 ChatGPT의 현재 Instant 모델을 사용해 보려면 모델을 openai/chat-latest로 설정하세요.
{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
chat-latest는 이동 별칭입니다. OpenAI는 이를 ChatGPT에서 사용되는 최신 Instant 모델로 문서화하며, 프로덕션 API 사용에는 gpt-5.5를 권장합니다. 따라서 해당 별칭 동작을 명시적으로 원하는 경우가 아니라면 openai/gpt-5.5를 안정적인 기본값으로 유지하세요. 이 별칭은 현재 medium 텍스트 상세도만 허용하므로, OpenClaw는 이 모델에 대해 호환되지 않는 OpenAI 텍스트 상세도 재정의를 정규화합니다.
OpenClaw는 openai/gpt-5.3-codex-spark를 노출하지 않습니다. 실제 OpenAI API 요청은 해당 모델을 거부하며, 현재 Codex 카탈로그도 이를 노출하지 않습니다.

​
네이티브 Codex 앱 서버 인증

네이티브 Codex 앱 서버 하네스는 openai/* 모델 참조와 생략된 런타임 구성 또는 provider/model agentRuntime.id: "codex"를 사용하지만, 인증은 여전히 계정 기반입니다. OpenClaw는 다음 순서로 인증을 선택합니다.
  1. 에이전트에 대해 정렬된 OpenAI 인증 프로필, 가능하면 auth.order.openai 아래의 프로필. 기존 openai-codex:* 프로필과 auth.order.openai-codex는 이전 설치에서도 계속 유효합니다.
  2. 로컬 Codex CLI ChatGPT 로그인과 같은 앱 서버의 기존 계정.
  3. 로컬 stdio 앱 서버 실행에 한해, 앱 서버가 계정이 없다고 보고하면서 여전히 OpenAI 인증을 요구하는 경우 CODEX_API_KEY, 그다음 OPENAI_API_KEY.
즉, Gateway 프로세스가 직접 OpenAI 모델이나 임베딩용 OPENAI_API_KEY를 함께 가지고 있다고 해서 로컬 ChatGPT/Codex 구독 로그인이 대체되지는 않습니다. Env API 키 폴백은 로컬 stdio 무계정 경로에서만 사용되며, WebSocket 앱 서버 연결로 전송되지 않습니다. 구독 스타일 Codex 프로필이 선택되면 OpenClaw는 생성된 stdio 앱 서버 자식 프로세스에서 CODEX_API_KEY와 OPENAI_API_KEY도 제외하고 선택된 자격 증명을 앱 서버 로그인 RPC를 통해 보냅니다. 해당 구독 프로필이 Codex 사용량 한도에 막히면, OpenClaw는 선택된 모델을 변경하거나 Codex 하네스를 벗어나지 않고 다음 순서의 openai:* API 키 프로필로 전환할 수 있습니다. 구독 재설정 시간이 지나면 구독 프로필은 다시 사용 가능해집니다.

​
이미지 생성

번들 openai Plugin은 image_generate 도구를 통해 이미지 생성을 등록합니다. 동일한 openai/gpt-image-2 모델 참조를 통해 OpenAI API 키 이미지 생성과 Codex OAuth 이미지 생성을 모두 지원합니다.
기능OpenAI API 키Codex OAuth
모델 참조openai/gpt-image-2openai/gpt-image-2
인증OPENAI_API_KEYOpenAI Codex OAuth 로그인
전송OpenAI Images APICodex Responses 백엔드
요청당 최대 이미지 수44
편집 모드사용 가능(최대 5개의 참조 이미지)사용 가능(최대 5개의 참조 이미지)
크기 재정의지원됨, 2K/4K 크기 포함지원됨, 2K/4K 크기 포함
종횡비 / 해상도OpenAI Images API로 전달되지 않음안전한 경우 지원되는 크기에 매핑됨
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}
공유 도구 매개변수, 제공자 선택, 장애 조치 동작은 이미지 생성을 참조하세요.
gpt-image-2는 OpenAI 텍스트-이미지 생성과 이미지 편집 모두의 기본값입니다. gpt-image-1.5, gpt-image-1, gpt-image-1-mini도 명시적 모델 재정의로 계속 사용할 수 있습니다. 투명 배경 PNG/WebP 출력에는 openai/gpt-image-1.5를 사용하세요. 현재 gpt-image-2 API는 background: "transparent"를 거부합니다. 투명 배경 요청의 경우 에이전트는 image_generate를 model: "openai/gpt-image-1.5", outputFormat: "png" 또는 "webp", 그리고 background: "transparent"와 함께 호출해야 합니다. 이전 openai.background provider 옵션도 계속 허용됩니다. OpenClaw는 또한 기본 openai/gpt-image-2 투명 요청을 gpt-image-1.5로 다시 작성하여 공개 OpenAI 및 OpenAI Codex OAuth 경로를 보호합니다. Azure 및 사용자 지정 OpenAI 호환 엔드포인트는 구성된 배포/모델 이름을 유지합니다. 헤드리스 CLI 실행에도 동일한 설정이 노출됩니다. 
openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json
입력 파일에서 시작할 때는 openclaw infer image edit와 함께 동일한 --output-format 및 --background 플래그를 사용합니다. --openai-background는 OpenAI 전용 별칭으로 계속 사용할 수 있습니다. Codex OAuth 설치의 경우 동일한 openai/gpt-image-2 참조를 유지하세요. openai-codex OAuth 프로필이 구성되어 있으면 OpenClaw는 저장된 OAuth 액세스 토큰을 확인하고 Codex Responses 백엔드를 통해 이미지 요청을 보냅니다. 해당 요청에 대해 먼저 OPENAI_API_KEY를 시도하거나 API 키로 조용히 폴백하지 않습니다. 대신 직접 OpenAI Images API 경로를 원할 때는 API 키, 사용자 지정 기본 URL 또는 Azure 엔드포인트로 models.providers.openai를 명시적으로 구성하세요. 해당 사용자 지정 이미지 엔드포인트가 신뢰할 수 있는 LAN/사설 주소에 있는 경우 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true도 설정하세요. OpenClaw는 이 옵트인이 없으면 사설/내부 OpenAI 호환 이미지 엔드포인트를 계속 차단합니다. 생성: 
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
투명 PNG 생성: 
/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
편집: 
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

​
동영상 생성

번들로 제공되는 openai Plugin은 video_generate 도구를 통해 동영상 생성을 등록합니다.
기능값
기본 모델openai/sora-2
모드텍스트-동영상, 이미지-동영상, 단일 동영상 편집
참조 입력이미지 1개 또는 동영상 1개
크기 재정의지원됨
기타 재정의aspectRatio, resolution, audio, watermark는 도구 경고와 함께 무시됩니다
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
공유 도구 매개변수, 제공자 선택, 장애 조치 동작은 동영상 생성을 참조하세요.

​
GPT-5 프롬프트 기여

OpenClaw는 제공자 전반의 GPT-5 계열 실행에 대해 공유 GPT-5 프롬프트 기여를 추가합니다. 이는 모델 ID별로 적용되므로 openai/gpt-5.5, openai-codex/gpt-5.5 같은 레거시 복구 전 참조, openrouter/openai/gpt-5.5, opencode/gpt-5.5 및 기타 호환 GPT-5 참조는 동일한 오버레이를 받습니다. 이전 GPT-4.x 모델에는 적용되지 않습니다. 번들로 제공되는 네이티브 Codex 하네스는 Codex 앱 서버 개발자 지침을 통해 동일한 GPT-5 동작과 Heartbeat 오버레이를 사용하므로, Codex를 통해 라우팅되는 openai/gpt-5.x 세션은 Codex가 나머지 하네스 프롬프트를 소유하더라도 동일한 후속 처리와 선제적 Heartbeat 지침을 유지합니다. GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 형태, 완료 검사, 검증에 대한 태그가 지정된 동작 계약을 추가합니다. 채널별 응답 및 무음 메시지 동작은 공유 OpenClaw 시스템 프롬프트와 아웃바운드 전달 정책에 남아 있습니다. GPT-5 지침은 일치하는 모델에 대해 항상 활성화됩니다. 친근한 상호작용 스타일 계층은 별도이며 구성할 수 있습니다.
값효과
"friendly" (기본값)친근한 상호작용 스타일 계층 활성화
"on""friendly"의 별칭
"off"친근한 스타일 계층만 비활성화
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}
값은 런타임에 대소문자를 구분하지 않으므로 "Off"와 "off" 모두 친근한 스타일 계층을 비활성화합니다.
공유 agents.defaults.promptOverlays.gpt5.personality 설정이 설정되지 않은 경우, 레거시 plugins.entries.openai.config.personality는 여전히 호환성 폴백으로 읽힙니다.

​
음성 및 말하기

번들로 제공되는 openai Plugin은 messages.tts 표면에 음성 합성을 등록합니다.
설정구성 경로기본값
모델messages.tts.providers.openai.modelgpt-4o-mini-tts
음성messages.tts.providers.openai.voicecoral
속도messages.tts.providers.openai.speed(설정 안 됨)
지침messages.tts.providers.openai.instructions(설정 안 됨, gpt-4o-mini-tts만 해당)
형식messages.tts.providers.openai.responseFormat음성 메모에는 opus, 파일에는 mp3
API 키messages.tts.providers.openai.apiKeyOPENAI_API_KEY로 폴백
기본 URLmessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
추가 본문messages.tts.providers.openai.extraBody / extra_body(설정 안 됨)
사용 가능한 모델: gpt-4o-mini-tts, tts-1, tts-1-hd. 사용 가능한 음성: alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.extraBody는 OpenClaw가 생성한 필드 뒤에 /audio/speech 요청 JSON으로 병합되므로, lang 같은 추가 키가 필요한 OpenAI 호환 엔드포인트에 사용하세요. 프로토타입 키는 무시됩니다.
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
채팅 API 엔드포인트에 영향을 주지 않고 TTS 기본 URL을 재정의하려면 OPENAI_TTS_BASE_URL을 설정하세요. OpenAI TTS는 여전히 API 키를 통해 구성됩니다. OAuth 전용 실시간 응답 음성의 경우 에이전트 모드 STT -> TTS 음성 대신 Realtime 음성 경로를 사용하세요.
번들로 제공되는 openai Plugin은 OpenClaw의 미디어 이해 전사 표면을 통해 배치 음성-텍스트 변환을 등록합니다.
  • 기본 모델: gpt-4o-transcribe
  • 엔드포인트: OpenAI REST /v1/audio/transcriptions
  • 입력 경로: multipart 오디오 파일 업로드
  • Discord 음성 채널 세그먼트와 채널 오디오 첨부 파일을 포함하여 인바운드 오디오 전사가 tools.media.audio를 사용하는 모든 곳에서 OpenClaw가 지원
인바운드 오디오 전사에 OpenAI를 강제하려면:
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
언어와 프롬프트 힌트는 공유 오디오 미디어 구성 또는 호출별 전사 요청에서 제공되는 경우 OpenAI로 전달됩니다.
번들된 openai Plugin은 Voice Call Plugin용 실시간 전사를 등록합니다.
설정구성 경로기본값
모델plugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
언어...openai.language(설정되지 않음)
프롬프트...openai.prompt(설정되지 않음)
무음 지속 시간...openai.silenceDurationMs800
VAD 임계값...openai.vadThreshold0.5
인증...openai.apiKey, OPENAI_API_KEY 또는 openai-codex OAuthAPI 키는 직접 연결합니다. OAuth는 Realtime 전사 클라이언트 시크릿을 발급합니다.
G.711 u-law(g711_ulaw / audio/pcmu) 오디오와 함께 wss://api.openai.com/v1/realtime에 대한 WebSocket 연결을 사용합니다. openai-codex OAuth만 구성된 경우 Gateway는 WebSocket을 열기 전에 임시 Realtime 전사 클라이언트 시크릿을 발급합니다. 이 스트리밍 제공자는 Voice Call의 실시간 전사 경로용입니다. Discord 음성은 현재 짧은 세그먼트를 녹음하고 대신 배치 tools.media.audio 전사 경로를 사용합니다.
번들된 openai Plugin은 Voice Call Plugin용 실시간 음성을 등록합니다.
설정구성 경로기본값
모델plugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime-2
음성...openai.voicealloy
Temperature(Azure 배포 브리지)...openai.temperature0.8
VAD 임계값...openai.vadThreshold0.5
무음 지속 시간...openai.silenceDurationMs500
접두사 패딩...openai.prefixPaddingMs300
추론 노력 수준...openai.reasoningEffort(설정되지 않음)
인증...openai.apiKey, OPENAI_API_KEY 또는 openai-codex OAuthBrowser Talk와 비 Azure 백엔드 브리지는 Codex OAuth를 사용할 수 있습니다.
gpt-realtime-2에서 사용할 수 있는 기본 제공 Realtime 음성: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. OpenAI는 최상의 Realtime 품질을 위해 marin 및 cedar를 권장합니다. 이는 위의 텍스트 음성 변환 음성과는 별도의 세트입니다. fable, nova, onyx 같은 TTS 음성이 Realtime 세션에 유효하다고 가정하지 마세요.
백엔드 OpenAI 실시간 브리지는 GA Realtime WebSocket 세션 형태를 사용하며, 이는 session.temperature를 허용하지 않습니다. Azure OpenAI 배포는 azureEndpoint 및 azureDeployment를 통해 계속 사용할 수 있으며 배포 호환 세션 형태를 유지합니다. 양방향 도구 호출과 G.711 u-law 오디오를 지원합니다.
실시간 음성은 세션이 생성될 때 선택됩니다. OpenAI는 대부분의 세션 필드를 나중에 변경할 수 있도록 허용하지만, 해당 세션에서 모델이 오디오를 내보낸 후에는 음성을 변경할 수 없습니다. OpenClaw는 현재 기본 제공 Realtime 음성 ID를 문자열로 노출합니다.
Control UI Talk는 Gateway가 발급한 임시 클라이언트 시크릿과 OpenAI Realtime API를 상대로 하는 직접 브라우저 WebRTC SDP 교환을 통해 OpenAI 브라우저 실시간 세션을 사용합니다. 직접 OpenAI API 키가 구성되지 않은 경우 Gateway는 선택된 openai-codex OAuth 프로필로 해당 클라이언트 시크릿을 발급할 수 있습니다. Gateway 릴레이와 Voice Call 백엔드 실시간 WebSocket 브리지는 네이티브 OpenAI 엔드포인트에 동일한 OAuth 대체 경로를 사용합니다. 유지관리자 라이브 검증은 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts로 사용할 수 있습니다. OpenAI 구간은 시크릿을 로깅하지 않고 백엔드 WebSocket 브리지와 브라우저 WebRTC SDP 교환을 모두 검증합니다.

​
Azure OpenAI 엔드포인트

번들된 openai 제공자는 기본 URL을 재정의하여 이미지 생성을 Azure OpenAI 리소스로 보낼 수 있습니다. 이미지 생성 경로에서 OpenClaw는 models.providers.openai.baseUrl의 Azure 호스트 이름을 감지하고 자동으로 Azure 요청 형태로 전환합니다.
실시간 음성은 별도의 구성 경로 (plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint)를 사용하며 models.providers.openai.baseUrl의 영향을 받지 않습니다. Azure 설정은 음성 및 발화 아래의 실시간 음성 아코디언을 참조하세요.
다음과 같은 경우 Azure OpenAI를 사용하세요.
  • Azure OpenAI 구독, 할당량 또는 엔터프라이즈 계약을 이미 보유하고 있는 경우
  • Azure가 제공하는 지역 데이터 상주 또는 규정 준수 제어가 필요한 경우
  • 기존 Azure 테넌시 내부에 트래픽을 유지하려는 경우

​
구성

번들된 openai 제공자를 통한 Azure 이미지 생성의 경우 models.providers.openai.baseUrl을 Azure 리소스로 지정하고 apiKey를 OpenAI Platform 키가 아닌 Azure OpenAI 키로 설정하세요. 
{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}
OpenClaw는 Azure 이미지 생성 경로에 대해 다음 Azure 호스트 접미사를 인식합니다.
  • *.openai.azure.com
  • *.services.ai.azure.com
  • *.cognitiveservices.azure.com
인식된 Azure 호스트의 이미지 생성 요청에 대해 OpenClaw는 다음을 수행합니다.
  • Authorization: Bearer 대신 api-key 헤더를 보냅니다.
  • 배포 범위 경로(/openai/deployments/{deployment}/...)를 사용합니다.
  • 각 요청에 ?api-version=...을 추가합니다.
  • Azure 이미지 생성 호출에 600초 기본 요청 제한 시간을 사용합니다. 호출별 timeoutMs 값은 여전히 이 기본값을 재정의합니다.
다른 기본 URL(공개 OpenAI, OpenAI 호환 프록시)은 표준 OpenAI 이미지 요청 형태를 유지합니다.
openai 제공자의 이미지 생성 경로에 대한 Azure 라우팅에는 OpenClaw 2026.4.22 이상이 필요합니다. 이전 버전은 사용자 지정 openai.baseUrl을 공개 OpenAI 엔드포인트처럼 처리하며 Azure 이미지 배포에서는 실패합니다.

​
API 버전

Azure 이미지 생성 경로에 대해 특정 Azure 프리뷰 또는 GA 버전을 고정하려면 AZURE_OPENAI_API_VERSION을 설정하세요. 
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
변수가 설정되지 않은 경우 기본값은 2024-12-01-preview입니다.

​
모델 이름은 배포 이름입니다

Azure OpenAI는 모델을 배포에 바인딩합니다. 번들된 openai provider를 통해 라우팅되는 Azure 이미지 생성 요청의 경우, OpenClaw의 model 필드는 공개 OpenAI 모델 ID가 아니라 Azure 포털에서 구성한 Azure 배포 이름이어야 합니다. gpt-image-2를 제공하는 gpt-image-2-prod라는 배포를 만드는 경우: 
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
동일한 배포 이름 규칙은 번들된 openai provider를 통해 라우팅되는 이미지 생성 호출에도 적용됩니다.

​
지역별 가용성

Azure 이미지 생성은 현재 일부 지역에서만 사용할 수 있습니다 (예: eastus2, swedencentral, polandcentral, westus3, uaenorth). 배포를 만들기 전에 Microsoft의 현재 지역 목록을 확인하고, 특정 모델이 해당 지역에서 제공되는지 확인하세요.

​
매개변수 차이

Azure OpenAI와 공개 OpenAI가 항상 동일한 이미지 매개변수를 허용하는 것은 아닙니다. Azure는 공개 OpenAI가 허용하는 옵션(예: gpt-image-2의 특정 background 값)을 거부하거나, 특정 모델 버전에서만 노출할 수 있습니다. 이러한 차이는 OpenClaw가 아니라 Azure와 기본 모델에서 비롯됩니다. Azure 요청이 유효성 검사 오류로 실패하면 Azure 포털에서 특정 배포와 API 버전이 지원하는 매개변수 집합을 확인하세요.
Azure OpenAI는 네이티브 전송 및 호환 동작을 사용하지만 OpenClaw의 숨겨진 어트리뷰션 헤더는 받지 않습니다. 고급 구성의 네이티브와 OpenAI 호환 경로 아코디언을 참조하세요.Azure에서 이미지 생성 이외의 채팅 또는 Responses 트래픽을 사용하는 경우, 온보딩 흐름이나 전용 Azure provider 구성을 사용하세요. openai.baseUrl만으로는 Azure API/인증 형태가 적용되지 않습니다. 별도의 azure-openai-responses/* provider가 있으며, 아래의 서버 측 Compaction 아코디언을 참조하세요.

​
고급 구성

OpenClaw는 openai/*에 대해 WebSocket 우선, SSE 폴백("auto")을 사용합니다."auto" 모드에서 OpenClaw는 다음을 수행합니다.
  • SSE로 폴백하기 전에 초기 WebSocket 실패를 한 번 재시도합니다
  • 실패 후 약 60초 동안 WebSocket을 성능 저하 상태로 표시하고 쿨다운 중에는 SSE를 사용합니다
  • 재시도와 재연결을 위해 안정적인 세션 및 턴 식별 헤더를 첨부합니다
  • 전송 변형 전반에서 사용량 카운터(input_tokens / prompt_tokens)를 정규화합니다
값동작
"auto" (기본값)WebSocket 우선, SSE 폴백
"sse"SSE만 강제
"websocket"WebSocket만 강제
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
관련 OpenAI 문서:
OpenClaw는 openai/*에 대한 공유 빠른 모드 토글을 노출합니다.
  • 채팅/UI: /fast status|on|off
  • 구성: agents.defaults.models["<provider>/<model>"].params.fastMode
활성화되면 OpenClaw는 빠른 모드를 OpenAI 우선순위 처리(service_tier = "priority")에 매핑합니다. 기존 service_tier 값은 보존되며, 빠른 모드는 reasoning 또는 text.verbosity를 다시 작성하지 않습니다.
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
세션 오버라이드가 구성보다 우선합니다. Sessions UI에서 세션 오버라이드를 지우면 세션이 구성된 기본값으로 돌아갑니다.
OpenAI의 API는 service_tier를 통해 우선순위 처리를 노출합니다. OpenClaw에서 모델별로 설정하세요.
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}
지원되는 값: auto, default, flex, priority.
serviceTier는 네이티브 OpenAI 엔드포인트(api.openai.com)와 네이티브 Codex 엔드포인트(chatgpt.com/backend-api)로만 전달됩니다. 두 provider 중 하나를 프록시를 통해 라우팅하면 OpenClaw는 service_tier를 그대로 둡니다.
직접 OpenAI Responses 모델(api.openai.com의 openai/*)의 경우, OpenAI Plugin의 Pi 하네스 스트림 래퍼가 서버 측 Compaction을 자동으로 활성화합니다.
  • store: true를 강제합니다(모델 호환성이 supportsStore: false를 설정하지 않는 한)
  • context_management: [{ type: "compaction", compact_threshold: ... }]를 삽입합니다
  • 기본 compact_threshold: contextWindow의 70%(사용할 수 없는 경우 80000)
이는 기본 제공 Pi 하네스 경로와 임베디드 실행에서 사용하는 OpenAI provider 훅에 적용됩니다. 네이티브 Codex 앱 서버 하네스는 Codex를 통해 자체 컨텍스트를 관리하며, OpenAI의 기본 agent 경로 또는 provider/모델 런타임 정책으로 구성됩니다.
Azure OpenAI Responses 같은 호환 엔드포인트에 유용합니다.
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction은 context_management 삽입만 제어합니다. 직접 OpenAI Responses 모델은 호환성이 supportsStore: false를 설정하지 않는 한 여전히 store: true를 강제합니다.
openai/*의 GPT-5 계열 실행에서 OpenClaw는 더 엄격한 임베디드 실행 계약을 사용할 수 있습니다.
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
strict-agentic에서 OpenClaw는 다음을 수행합니다.
  • 도구 작업을 사용할 수 있을 때 계획만 있는 턴을 더 이상 성공적인 진행으로 간주하지 않습니다
  • 즉시 실행 유도로 턴을 재시도합니다
  • 상당한 작업에는 update_plan을 자동으로 활성화합니다
  • 모델이 계속 계획만 하고 실행하지 않으면 명시적인 차단 상태를 표시합니다
OpenAI 및 Codex GPT-5 계열 실행으로만 범위가 지정됩니다. 다른 provider와 이전 모델 계열은 기본 동작을 유지합니다.
OpenClaw는 직접 OpenAI, Codex, Azure OpenAI 엔드포인트를 일반 OpenAI 호환 /v1 프록시와 다르게 처리합니다.네이티브 경로(openai/*, Azure OpenAI):
  • OpenAI none effort를 지원하는 모델에 대해서만 reasoning: { effort: "none" }을 유지합니다
  • reasoning.effort: "none"을 거부하는 모델 또는 프록시에 대해 비활성화된 reasoning을 생략합니다
  • 도구 스키마를 기본적으로 엄격 모드로 설정합니다
  • 검증된 네이티브 호스트에만 숨겨진 어트리뷰션 헤더를 첨부합니다
  • OpenAI 전용 요청 형태(service_tier, store, reasoning 호환성, prompt-cache 힌트)를 유지합니다
프록시/호환 경로:
  • 더 느슨한 호환 동작을 사용합니다
  • 네이티브가 아닌 openai-completions 페이로드에서 Completions store를 제거합니다
  • OpenAI 호환 Completions 프록시에 대해 고급 params.extra_body/params.extraBody 통과 JSON을 허용합니다
  • vLLM 같은 OpenAI 호환 Completions 프록시에 대해 params.chat_template_kwargs를 허용합니다
  • 엄격한 도구 스키마 또는 네이티브 전용 헤더를 강제하지 않습니다
Azure OpenAI는 네이티브 전송 및 호환 동작을 사용하지만 숨겨진 어트리뷰션 헤더는 받지 않습니다.

​
관련 항목

모델 선택

provider, 모델 참조, 장애 조치 동작 선택.

이미지 생성

공유 이미지 도구 매개변수와 provider 선택.

비디오 생성

공유 비디오 도구 매개변수와 provider 선택.

OAuth 및 인증

인증 세부 정보와 자격 증명 재사용 규칙.