OpenAI

OpenClaw는 직접 API 키 인증과 ChatGPT/Codex 구독 인증 모두에 하나의 제공자 ID인 openai을 사용합니다. openai/*은 표준 모델 경로입니다. 런타임 정책이 설정되지 않았거나 auto인 임베디드 에이전트 턴에서는 OpenAI의 경로 정보에 따라 OpenClaw가 번들 Codex 앱 서버 런타임을 암시적으로 선택할 수 있는지가 결정됩니다. openai/* 접두사만으로는 런타임이 선택되지 않습니다.

• 에이전트 모델 - 명시적인 agentRuntime 구성 또는 OpenAI의 암시적 경로 정책으로 선택된 런타임을 통해 openai/*을 사용합니다. ChatGPT/Codex 구독을 사용하려면 Codex 인증으로 로그인하고, 키 기반 결제를 원하면 API 키 인증 프로필을 구성하십시오.
• 비에이전트 OpenAI API - OPENAI_API_KEY 또는 openai API 키 인증 프로필을 통해 사용량에 따라 과금되는 직접 OpenAI Platform 액세스입니다.
• 레거시 구성 - openclaw doctor --fix이 codex/* 및 openai-codex/* 참조를 openai/*과 모델 범위의 agentRuntime.id: "codex"로 복구합니다.

OpenAI는 OpenClaw와 같은 외부 도구 및 워크플로에서 구독 OAuth를 사용하는 것을 명시적으로 지원합니다.

사용량 및 비용 추적

OpenClaw는 구독 할당량과 Platform API 청구를 구분합니다.

• ChatGPT/Codex OAuth에는 구독 요금제, 할당량 기간 및 크레딧 잔액이 표시됩니다.
• OPENAI_ADMIN_KEY에는 일별 지출, 요청/토큰 합계, 상위 모델 및 비용 범주를 포함하여 제공자가 보고한 30일간의 조직 비용과 완료 사용량이 Control UI의 사용량에 표시됩니다.
• OPENAI_PROJECT_ID은 선택적으로 Admin API 기록의 범위를 한 프로젝트로 제한합니다.
• OpenClaw는 OPENAI_API_KEY 또는 openai 추론 프로필을 조직 API에 절대 전송하지 않습니다. 이러한 자격 증명은 사용자 지정, Azure 또는 에이전트 로컬 엔드포인트에 속할 수 있습니다.

명시적인 Admin 키가 OAuth보다 우선합니다. 제공자가 보고한 기록은 OpenClaw가 세션에서 추산한 비용과 병합되지 않으며, 다른 클라이언트의 API 활동과 제공자 측 청구 조정이 포함될 수 있습니다.

OpenAI의 API 사용량 대시보드 문서에서는 사용량 데이터에 필요한 조직 소유자 권한과 명시적인 Usage Dashboard 권한을 설명합니다.

제공자, 모델, 런타임 및 채널은 서로 별개의 계층입니다. 이러한 레이블을 혼동하고 있다면 구성을 변경하기 전에 에이전트 런타임을 읽으십시오.

빠른 선택

이름 매핑

암시적 에이전트 런타임

제공자/모델 agentRuntime 정책이 설정되지 않았거나 auto이면 OpenAI가 소유한 제공자 경로 정책이 유효 엔드포인트와 어댑터를 바탕으로 암시적 런타임을 선택합니다.

명시적인 비기본 제공자/모델 agentRuntime.id이 계속 우선합니다. 예를 들어 agentRuntime.id: "openclaw"은 다른 조건에서는 Codex를 사용할 수 있는 경로를 OpenClaw로 유지하며, agentRuntime.id: "codex"은 Codex를 요구하고 유효 경로가 Codex 호환으로 선언되지 않은 경우 실패로 종료합니다. 런타임 선택은 자격 증명 유형이나 청구 방식을 변경하지 않습니다. Platform API 키 인증과 ChatGPT/Codex 구독 인증은 계속 구분됩니다.

openclaw doctor --fix은 레거시 codex/* 및 openai-codex/* 모델 참조, 레거시 Codex 인증 프로필 ID, 레거시 Codex 인증 순서 항목을 표준 openai 경로로 마이그레이션합니다. 마이그레이션된 모델 참조에는 모델 범위의 agentRuntime.id: "codex"이 지정됩니다. 새 인증 순서 구성에는 auth.order.openai을 사용하십시오.

GPT-5.6 제한적 프리뷰

OpenClaw는 정확한 openai/gpt-5.6-sol, openai/gpt-5.6-terra 및 openai/gpt-5.6-luna 모델 ID를 인식합니다. 현재 카탈로그에서 세 모델 모두 xhigh 및 max 추론을 제공합니다. OpenAI는 Sol을 플래그십 티어, Terra를 균형 잡힌 티어, Luna를 빠르고 비용이 낮은 티어로 설명합니다. GPT-5.6 출시 발표와 액세스 가이드를 참조하십시오.

직접 OpenAI API 키 인증을 사용하는 경우 기본 openai/gpt-5.6 ID는 Sol의 별칭이며 새로운 설정의 기본값입니다. 네이티브 Codex 카탈로그는 해당 직접 API 별칭을 클라이언트 측에서 적용하지 않습니다. 워크스페이스 액세스 권한에 따라 정확한 Sol, Terra 및 Luna ID가 표시될 수 있습니다. 따라서 새로운 ChatGPT/Codex OAuth 설정은 openai/gpt-5.6-sol을 사용합니다. 다음 명령으로 현재 계정을 확인하십시오.

openclaw models list --provider openai

API 조직과 Codex 워크스페이스의 액세스 권한은 다를 수 있습니다. GPT-5.6을 사용할 수 없으면 GPT-5.5를 명시적으로 선택하십시오.

openclaw models set openai/gpt-5.5

OpenClaw는 업스트림 액세스 오류를 표시하며 GPT-5.6 선택을 GPT-5.5로 자동 교체하지 않습니다.

OpenClaw 기능 지원 범위

메모리 임베딩

OpenClaw는 memory_search 인덱싱 및 쿼리 임베딩에 OpenAI 또는 OpenAI 호환 임베딩 엔드포인트를 사용할 수 있습니다.

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

비대칭 임베딩 레이블이 필요한 OpenAI 호환 엔드포인트의 경우 memorySearch 아래에 queryInputType 및 documentInputType을 설정하십시오. OpenClaw는 이를 제공자별 input_type 요청 필드로 전달합니다. 쿼리 임베딩은 queryInputType을 사용하고, 인덱싱된 메모리 청크와 일괄 인덱싱은 documentInputType을 사용합니다. 전체 예시는 메모리 구성 참조를 참조하십시오.

시작하기

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

openclaw models auth login --provider openai --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

네이티브 Codex 앱 서버 인증

네이티브 Codex 앱 서버 하네스는 적격한 정확한 공식 HTTPS 경로가 암시적으로 선택하거나 공급자/모델 agentRuntime.id: "codex"이 명시적으로 선택할 때 openai/* 모델 참조를 사용합니다. 인증은 여전히 계정 기반입니다. OpenClaw는 다음 순서로 인증을 선택합니다.

1. 에이전트에 대해 순서가 지정된 OpenAI 인증 프로필이며, 가급적 auth.order.openai 아래에 둡니다. 이전 레거시 Codex 인증 프로필 ID와 인증 순서를 마이그레이션하려면 openclaw doctor --fix을 실행하십시오.
2. 로컬 Codex CLI ChatGPT 로그인과 같은 앱 서버의 기존 계정입니다. 기본 격리 에이전트 홈의 경우 OpenClaw는 로그인 RPC를 통해 해당 네이티브 CLI 계정을 앱 서버에 연결합니다. CLI의 구성, Plugin 또는 스레드 저장소는 공유하지 않습니다.
3. 로컬 stdio 앱 서버 실행에만 해당하며, 앱 서버가 계정이 없다고 보고하는 경우에만 CODEX_API_KEY, 그다음 OPENAI_API_KEY을 사용합니다.

Gateway 프로세스에 직접 OpenAI 모델이나 임베딩을 위한 OPENAI_API_KEY이 있다고 해서 로컬 ChatGPT/Codex 구독 로그인이 대체되지는 않습니다. 환경 변수 API 키 대체 경로는 로컬 stdio의 계정 없음 경로에만 적용되며 WebSocket 앱 서버 연결을 통해 전송되지 않습니다. 구독 유형 Codex 프로필을 선택하면 OpenClaw는 생성된 stdio 앱 서버 자식 프로세스에서 CODEX_API_KEY과 OPENAI_API_KEY도 제외하고, 대신 앱 서버 로그인 RPC를 통해 선택한 자격 증명을 전송합니다.

해당 구독 프로필이 Codex 사용량 한도로 차단되면 OpenClaw는 Codex에서 알린 재설정 시간까지 프로필을 차단 상태로 표시하고, 선택한 모델을 변경하거나 Codex 하네스에서 이탈하지 않은 채 인증 순서에 따라 다음 openai:* 프로필로 전환합니다. 재설정 시간이 지나면 구독 프로필을 다시 사용할 수 있습니다.

이미지 생성

번들 openai Plugin은 image_generate 도구를 통해 이미지 생성을 등록합니다. 동일한 openai/gpt-image-2 모델 참조를 통해 OpenAI API 키 및 Codex OAuth 이미지 생성을 모두 지원합니다.

{  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"을 거부합니다.

투명 배경 요청의 경우 model: "openai/gpt-image-1.5", outputFormat: "png" 또는 "webp" 및 background: "transparent"과 함께 image_generate을 호출하십시오. 이전 openai.background 공급자 옵션도 계속 허용됩니다. 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 "투명한 배경의 단순한 빨간색 원형 스티커" \  --json

입력 파일에서 시작할 때는 openclaw infer image edit과 함께 동일한 --output-format 및 --background 플래그를 사용하십시오. --openai-background은 OpenAI 전용 별칭으로 계속 사용할 수 있습니다. OpenAI Images의 품질과 비용을 제어하려면 --quality low|medium|high|auto을 사용하십시오. image generate 또는 image edit에서 OpenAI의 검토 힌트를 전달하려면 --openai-moderation low|auto을 사용하십시오.

ChatGPT/Codex OAuth 설치에서는 동일한 openai/gpt-image-2 참조를 유지하십시오. openai 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="macOS용 OpenClaw의 세련된 출시 포스터" size=3840x2160 count=1

투명 PNG 생성:

/tool image_generate model=openai/gpt-image-1.5 prompt="투명한 배경의 단순한 빨간색 원형 스티커" outputFormat=png background=transparent

편집:

/tool image_generate model=openai/gpt-image-2 prompt="객체 모양은 유지하고 재질을 반투명 유리로 변경" image=/path/to/reference.png size=1024x1536

동영상 생성

번들 openai Plugin은 video_generate 도구를 통해 동영상 생성을 등록합니다.

OpenAI 이미지-비디오 요청은 이미지 input_reference와 함께 POST /v1/videos을 사용합니다. 단일 비디오 편집은 업로드된 비디오를 video 필드에 넣고 POST /v1/videos/edits을 사용합니다.

{  agents: {    defaults: {      videoGenerationModel: { primary: "openai/sora-2" },    },  },}

GPT-5 프롬프트 기여

OpenClaw는 openai 제공자의 GPT-5 계열 모델에 공유 GPT-5 프롬프트 기여를 추가합니다(openai/*으로 정규화되는 복구 전의 레거시 Codex 참조 포함). OpenRouter 또는 opencode 경로와 같이 GPT-5 계열 모델 ID도 제공하는 다른 제공자는 이 오버레이를 받지 않습니다. 이 오버레이는 모델 ID만이 아니라 제공자 ID openai에 따라 적용됩니다. 이전 GPT-4.x 모델에는 절대 적용되지 않습니다.

네이티브 Codex 앱 서버 하네스는 개발자 지침을 통해 페르소나/도구 규율 동작 계약이나 친근한 상호작용 스타일 오버레이를 받지 않습니다. 네이티브 Codex는 Codex가 소유한 기본 동작, 모델 및 프로젝트 문서 동작을 유지하며, OpenClaw는 네이티브 스레드에서 Codex의 기본 제공 성격을 비활성화하여 에이전트 작업 공간의 성격 파일이 계속 권위 있는 기준이 되도록 합니다. OpenClaw는 네이티브 Codex 스레드에 런타임 컨텍스트만 제공합니다. 여기에는 채널 전달, OpenClaw 동적 도구, ACP 위임, 작업 공간 컨텍스트 및 OpenClaw Skills가 포함됩니다. 같은 기여의 Heartbeat 안내 텍스트는 유일한 예외입니다. 네이티브 Codex Heartbeat 턴에는 이 텍스트가 제공되며, 공유 프롬프트 기여 훅이 아니라 전용 협업 지침으로 삽입됩니다.

GPT-5 기여는 일치하는 OpenClaw 조립 프롬프트에 페르소나 지속성, 실행 안전성, 도구 규율, 출력 형식, 완료 검사 및 검증을 위한 태그가 지정된 동작 계약을 추가합니다. 채널별 응답 및 무응답 메시지 동작은 공유 OpenClaw 시스템 프롬프트와 발신 전달 정책에 유지됩니다. 친근한 상호작용 스타일 계층은 별도이며 구성할 수 있습니다.

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

음성 및 말하기

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

Azure OpenAI 엔드포인트

번들 openai 공급자는 기본 URL을 재정의하여 이미지 생성을 Azure OpenAI 리소스로 지정할 수 있습니다. 이미지 생성 경로에서 OpenClaw는 models.providers.openai.baseUrl의 Azure 호스트 이름을 감지하고 Azure 요청 형식으로 자동 전환합니다.

다음과 같은 경우 Azure OpenAI를 사용하십시오.

• 이미 Azure OpenAI 구독, 할당량 또는 엔터프라이즈 계약이 있는 경우
• Azure에서 제공하는 지역별 데이터 상주 또는 규정 준수 제어가 필요한 경우
• 기존 Azure 테넌트 내에서 트래픽을 유지하려는 경우

구성

번들 openai 공급자를 통해 Azure 이미지 생성을 사용하려면 models.providers.openai.baseUrl이 Azure 리소스를 가리키도록 하고, apiKey을 Azure OpenAI 키(OpenAI Platform 키가 아님)로 설정하십시오.

{  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 이미지 요청 형식을 유지합니다.

API 버전

Azure 이미지 생성 경로에서 특정 Azure 미리 보기 또는 GA 버전을 고정하려면 AZURE_OPENAI_API_VERSION을 설정하십시오.

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

변수를 설정하지 않으면 기본값은 2024-12-01-preview입니다.

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

Azure OpenAI는 모델을 배포에 바인딩합니다. 번들 openai 공급자를 통해 라우팅되는 Azure 이미지 생성 요청의 경우, OpenClaw의 model 필드는 공개 OpenAI 모델 ID가 아니라 Azure 포털에서 구성한 Azure 배포 이름이어야 합니다.

gpt-image-2을 제공하는 gpt-image-2-prod이라는 배포를 생성한 경우:

/tool image_generate model=openai/gpt-image-2-prod prompt="깔끔한 포스터" size=1024x1024 count=1

번들 openai 공급자를 통해 라우팅되는 모든 이미지 생성 호출에도 동일한 배포 이름 규칙이 적용됩니다.

지역별 가용성

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

매개변수 차이

Azure OpenAI와 공개 OpenAI는 항상 동일한 이미지 매개변수를 허용하지는 않습니다. Azure는 공개 OpenAI에서 허용하는 옵션(예: gpt-image-2의 특정 background 값)을 거부하거나 특정 모델 버전에서만 노출할 수 있습니다. 이러한 차이는 OpenClaw가 아니라 Azure와 기반 모델에서 비롯됩니다. Azure 요청이 유효성 검사 오류로 실패하면 Azure 포털에서 해당 배포와 API 버전이 지원하는 매개변수 집합을 확인하십시오.

고급 구성

아래의 모델별 params 예시는 OpenClaw의 임베디드 공급자 요청 형식을 결정합니다. 이를 구성하면 명시적으로 작성된 요청 동작이 되므로, 그 외에는 적격인 auto 경로도 Codex를 암시적으로 선택하지 않고 OpenClaw에 유지됩니다. 네이티브 Codex 앱 서버 하네스는 자체 전송 및 요청 설정을 관리합니다. 유효한 경로가 Codex 호환으로 선언되지 않은 경우 명시적 agentRuntime.id: "codex"은 안전하게 실패합니다.

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { serviceTier: "priority" } },      },    },  },}

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedAgent: { executionContract: "default" },    },  },}

관련 항목