OpenAI

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 사용을 명시적으로 지원합니다.

공급자, 모델, 런타임, 채널은 별도의 계층입니다. 이러한 레이블이 서로 혼동되고 있다면 구성을 변경하기 전에 에이전트 런타임을 읽으세요.

빠른 선택

이름 매핑

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

이는 구성에 의도적으로 openai/* 모델 참조가 포함되면서도 인증 프로필은 Codex 호환 자격 증명을 가리킬 수 있음을 의미합니다. 새 구성에는 auth.order.openai를 선호하세요. 기존 openai-codex:* 프로필과 auth.order.openai-codex는 계속 지원됩니다. openclaw doctor --fix는 레거시 openai-codex/* 모델 참조를 표준 OpenAI 모델 경로로 다시 씁니다.

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: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

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

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

openclaw models list --provider openai-codex

{  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-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

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

네이티브 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 이미지 생성을 모두 지원합니다.

{  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 도구를 통해 동영상 생성을 등록합니다.

{  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 지침은 일치하는 모델에 대해 항상 활성화됩니다. 친근한 상호작용 스타일 계층은 별도이며 구성할 수 있습니다.

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

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

음성 및 말하기

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", voice: "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를 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 이미지 요청 형태를 유지합니다.

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: true } },      },    },  },}

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

관련 항목