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 직접 액세스입니다.
• 레거시 구성 - 이전 Codex 모델 참조 및 프로필 ID는 openclaw doctor --fix에 의해 openai/*로 복구됩니다.

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

사용량 및 비용 추적

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

• ChatGPT/Codex OAuth에는 구독 요금제, 할당량 기간 및 크레딧 잔액이 표시됩니다.
• OPENAI_ADMIN_KEY를 사용하면 Control UI의 사용량에서 제공자가 보고한 30일간의 조직 비용과 완료 사용량을 확인할 수 있으며, 여기에는 일별 지출, 요청/토큰 합계, 상위 모델 및 비용 범주가 포함됩니다.
• 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 모델 참조, 레거시 Codex 인증 프로필 ID 및 레거시 Codex 인증 순서 항목을 표준 openai 경로로 마이그레이션합니다. 새 인증 순서 구성에는 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 이미지 생성 호출에 600s의 기본 요청 제한 시간을 사용합니다. 호출별 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" },    },  },}

관련 항목