OpenAI

OpenAI는 GPT 모델용 개발자 API를 제공하며, Codex는 OpenAI의 Codex 클라이언트를 통해 ChatGPT 플랜 코딩 에이전트로도 사용할 수 있습니다. OpenClaw는 구성의 예측 가능성을 유지하기 위해 이 표면들을 분리합니다.

OpenClaw는 openai/*를 표준 OpenAI 모델 경로로 사용합니다. OpenAI 모델의 임베디드 에이전트 턴은 기본적으로 네이티브 Codex 앱 서버 런타임을 통해 실행됩니다. 직접 OpenAI API 키 인증은 이미지, 임베딩, 음성, 실시간과 같은 비에이전트 OpenAI 표면에서 계속 사용할 수 있습니다.

• 에이전트 모델 - Codex 런타임을 통한 openai/* 모델입니다. ChatGPT/Codex 구독 사용에는 openai-codex 인증으로 로그인하거나, 의도적으로 API 키 인증을 사용하려면 openai-codex API 키 프로필을 구성하세요.
• 비에이전트 OpenAI API - OPENAI_API_KEY 또는 OpenAI API 키 온보딩을 통해 사용량 기반 과금으로 직접 OpenAI Platform에 접근합니다.
• 레거시 구성 - openai-codex/* 모델 참조는 openclaw doctor --fix에 의해 openai/*와 Codex 런타임으로 복구됩니다.

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

프로바이더, 모델, 런타임, 채널은 서로 다른 계층입니다. 이 라벨들이 서로 혼동되고 있다면 구성을 변경하기 전에 에이전트 런타임을 읽으세요.

# 빠른 선택

# 이름 매핑

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

즉, 구성에는 의도적으로 openai/* 모델 참조와 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

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

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

# 네이티브 Codex app-server 인증

네이티브 Codex app-server 하네스는 openai/* 모델 참조와 생략된 런타임 구성 또는 agentRuntime.id: "codex"를 사용하지만, 인증은 여전히 계정 기반입니다. OpenClaw는 다음 순서로 인증을 선택합니다.

1. 에이전트에 바인딩된 명시적 OpenClaw openai-codex 인증 프로필.
2. 로컬 Codex CLI ChatGPT 로그인과 같은 app-server의 기존 계정.
3. 로컬 stdio app-server 실행에 한해, app-server가 계정이 없다고 보고하고 여전히 OpenAI 인증이 필요한 경우 CODEX_API_KEY, 그다음 OPENAI_API_KEY.

즉, Gateway 프로세스에 직접 OpenAI 모델이나 임베딩용 OPENAI_API_KEY가 있다는 이유만으로 로컬 ChatGPT/Codex 구독 로그인이 대체되지는 않습니다. 환경 API 키 대체는 로컬 stdio 무계정 경로에만 해당하며, WebSocket app-server 연결로 전송되지 않습니다. 구독 방식 Codex 프로필이 선택되면 OpenClaw는 생성된 stdio app-server 자식 프로세스에서 CODEX_API_KEY와 OPENAI_API_KEY도 제외하고, 선택된 자격 증명을 app-server login RPC를 통해 보냅니다.

# 이미지 생성

번들 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 전용 별칭으로 계속 사용할 수 있습니다.

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 app-server 개발자 지침을 통해 동일한 GPT-5 동작과 Heartbeat 오버레이를 사용하므로, agentRuntime.id: "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 공급자는 Base 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 값은 여전히 이 기본값을 재정의합니다.

다른 Base URL(공개 OpenAI, OpenAI 호환 프록시)은 표준 OpenAI 이미지 요청 형식을 유지합니다.

# API 버전

Azure 이미지 생성 경로에 대해 특정 Azure preview 또는 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="A clean poster" 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 버전이 지원하는 매개변수 집합을 확인하세요.

# 고급 구성

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

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

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

# 관련 항목