OpenAI

OpenAI는 GPT 모델용 개발자 API를 제공하며, Codex는 OpenAI의 Codex 클라이언트를 통해 ChatGPT 플랜 코딩 에이전트로도 사용할 수 있습니다. OpenClaw는 두 인증 형태 모두에 하나의 provider id인 openai를 사용합니다.

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 액세스입니다.
• 레거시 구성 - 레거시 Codex 모델 참조는 openclaw doctor --fix에 의해 openai/*와 Codex 런타임으로 복구됩니다.

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

Provider, 모델, 런타임, 채널은 별개의 계층입니다. 이러한 라벨이 서로 섞이고 있다면 구성을 변경하기 전에 에이전트 런타임을 읽어보세요.

빠른 선택

이름 매핑

이름은 비슷하지만 서로 바꿔 쓸 수 없습니다.

즉, 구성에는 의도적으로 openai/* 모델 참조가 포함될 수 있으며 인증 프로필은 API 키 또는 ChatGPT/Codex OAuth 자격 증명 중 하나를 가리킬 수 있습니다. 구성에는 auth.order.openai를 사용하세요. openclaw doctor --fix는 레거시 Codex 모델 참조, 레거시 Codex 인증 프로필 ID, 레거시 Codex 인증 순서를 표준 OpenAI 경로로 다시 씁니다.

GPT-5.6 제한 프리뷰

OpenClaw는 세 가지 공개 GPT-5.6 모델 ID를 인식합니다.

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

세 모델 모두 현재 Codex 앱 서버 카탈로그에서 max 추론을 노출합니다. OpenAI 출시 발표에서는 Sol을 플래그십 티어, Terra를 균형형 티어, Luna를 빠르고 비용이 더 낮은 티어로 설명합니다. GPT-5.6 출시 발표와 프리뷰 액세스 가이드를 참고하세요.

프리뷰 기간에는 액세스가 허용 목록 방식이며 API와 Codex에 별도로 부여될 수 있습니다. 유료 ChatGPT 플랜만으로는 액세스가 부여되지 않습니다. OpenClaw는 openai/gpt-5.5를 기본값으로 유지합니다. 액세스 없이 GPT-5.6 참조를 선택하면 조용히 폴백하지 않고 업스트림 액세스 오류를 반환합니다.

OpenClaw 기능 범위

메모리 임베딩

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

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

비대칭 임베딩 라벨이 필요한 OpenAI 호환 엔드포인트의 경우 memorySearch 아래에 queryInputType과 documentInputType을 설정하세요. OpenClaw는 이를 provider별 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.5" } } },}

{  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.5

openclaw models list --provider openai

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  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 앱 서버 하네스는 openai/* 모델 참조와 생략된 런타임 구성 또는 provider/model agentRuntime.id: "codex"를 사용하지만, 인증은 여전히 계정 기반입니다. OpenClaw는 다음 순서로 인증을 선택합니다.

1. 에이전트에 대해 순서가 지정된 OpenAI 인증 프로필. 가급적 auth.order.openai 아래에 둡니다. 이전 레거시 Codex 인증 프로필 ID와 레거시 Codex 인증 순서를 마이그레이션하려면 openclaw doctor --fix를 실행하세요.
2. 로컬 Codex CLI ChatGPT 로그인과 같은 앱 서버의 기존 계정.
3. 로컬 stdio 앱 서버 실행에 한해, 앱 서버가 계정이 없다고 보고하면서도 OpenAI 인증을 계속 요구하는 경우 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 하네스에서 벗어나지 않고 다음 순서의 openai:* API 키 프로필로 전환할 수 있습니다. 구독 초기화 시간이 지나면 구독 프로필은 다시 사용할 수 있습니다.

이미지 생성

번들 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 "A simple red circle sticker on a transparent background" \  --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 ref를 유지하세요. 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="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 이미지-비디오 요청은 이미지 input_reference와 함께 POST /v1/videos를 사용합니다. 단일 비디오 편집은 업로드된 비디오를 video 필드에 넣어 POST /v1/videos/edits를 사용합니다.

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

GPT-5 프롬프트 기여

OpenClaw는 OpenClaw가 조립한 프롬프트 표면의 GPT-5 계열 실행에 공유 GPT-5 프롬프트 기여를 추가합니다. 이는 모델 id에 따라 적용되므로 레거시 사전 복구 ref(레거시 Codex GPT-5.5 ref), openrouter/openai/gpt-5.5, opencode/gpt-5.5 및 기타 호환 GPT-5 ref와 같은 OpenClaw/제공자 경로는 동일한 오버레이를 받습니다. 이전 GPT-4.x 모델에는 적용되지 않습니다.

번들된 네이티브 Codex 하네스는 Codex 앱 서버 개발자 지침을 통해 이 OpenClaw GPT-5 오버레이를 받지 않습니다. 네이티브 Codex는 Codex가 소유한 기본, 모델, 프로젝트 문서 동작을 유지하며, OpenClaw는 네이티브 스레드에서 Codex의 내장 퍼스낼리티를 비활성화하여 에이전트 작업공간 퍼스낼리티 파일이 계속 권위 있는 기준이 되도록 합니다. OpenClaw는 채널 전달, OpenClaw 동적 도구, ACP 위임, 작업공간 컨텍스트, OpenClaw Skills와 같은 런타임 컨텍스트만 기여합니다.

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 provider는 기본 URL을 재정의하여 이미지 생성을 위한 Azure OpenAI 리소스를 대상으로 할 수 있습니다. 이미지 생성 경로에서 OpenClaw는 models.providers.openai.baseUrl의 Azure 호스트 이름을 감지하고 Azure의 요청 형식으로 자동 전환합니다.

다음과 같은 경우 Azure OpenAI를 사용하세요.

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

구성

번들된 openai provider를 통해 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 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 버전이 지원하는 매개변수 집합을 확인하세요.

고급 구성

{  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: "strict-agentic" },    },  },}

관련 항목