OpenAI

OpenAI, GPT modelleri için geliştirici API'leri sağlar ve Codex, OpenAI'ın Codex istemcileri üzerinden ChatGPT planı kapsamında bir kodlama ajanı olarak da kullanılabilir. OpenClaw, yapılandırmanın öngörülebilir kalması için bu yüzeyleri ayrı tutar.

OpenClaw, standart OpenAI model rotası olarak openai/* kullanır. OpenAI modellerindeki gömülü ajan turları varsayılan olarak yerel Codex app-server çalışma zamanı üzerinden çalışır; doğrudan OpenAI API anahtarı kimlik doğrulaması ise görüntüler, embeddings, konuşma ve realtime gibi ajan olmayan OpenAI yüzeyleri için kullanılabilir olmaya devam eder.

• Ajan modelleri - Codex çalışma zamanı üzerinden openai/* modelleri; ChatGPT/Codex aboneliği kullanımı için openai-codex kimlik doğrulamasıyla oturum açın veya özellikle API anahtarı kimlik doğrulaması istediğinizde bir openai-codex API anahtarı profili yapılandırın.
• Ajan olmayan OpenAI API'leri - OPENAI_API_KEY veya OpenAI API anahtarı başlangıç kurulumu üzerinden kullanıma dayalı faturalandırmayla doğrudan OpenAI Platform erişimi.
• Eski yapılandırma - openai-codex/* model referansları openclaw doctor --fix tarafından openai/* ve Codex çalışma zamanına onarılır.

OpenAI, OpenClaw gibi harici araçlarda ve iş akışlarında abonelik OAuth kullanımını açıkça destekler.

Sağlayıcı, model, çalışma zamanı ve kanal ayrı katmanlardır. Bu etiketler birbirine karışıyorsa yapılandırmayı değiştirmeden önce Ajan çalışma zamanları bölümünü okuyun.

# Hızlı seçim

# Adlandırma haritası

Adlar benzerdir ancak birbirinin yerine kullanılamaz:

Bu, bir yapılandırmanın bilerek hem openai/* model referansları hem de openai-codex kimlik doğrulama profilleri içerebileceği anlamına gelir. openclaw doctor --fix, eski openai-codex/* model referanslarını standart OpenAI model rotasına yeniden yazar.

# OpenClaw özellik kapsamı

# Bellek embeddings

OpenClaw, memory_search dizinleme ve sorgu embeddings için OpenAI veya OpenAI uyumlu bir embedding uç noktası kullanabilir:

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

Asimetrik embedding etiketleri gerektiren OpenAI uyumlu uç noktalar için memorySearch altında queryInputType ve documentInputType ayarlayın. OpenClaw bunları sağlayıcıya özgü input_type istek alanları olarak iletir: sorgu embeddings queryInputType kullanır; dizinlenmiş bellek parçaları ve toplu dizinleme documentInputType kullanır. Tam örnek için Bellek yapılandırma referansına bakın.

# Başlarken

Tercih ettiğiniz kimlik doğrulama yöntemini seçin ve kurulum adımlarını izleyin.

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 }],
      },
    },
  },
}

# Yerel Codex app-server kimlik doğrulaması

Yerel Codex app-server koşum takımı openai/* model ref'lerini ve atlanmış çalışma zamanı yapılandırmasını veya agentRuntime.id: "codex" kullanır, ancak kimlik doğrulaması hâlâ hesap tabanlıdır. OpenClaw kimlik doğrulamayı şu sırayla seçer:

1. Ajana bağlı açık bir OpenClaw openai-codex kimlik doğrulama profili.
2. App-server'ın mevcut hesabı, örneğin yerel bir Codex CLI ChatGPT oturum açması.
3. Yalnızca yerel stdio app-server başlatmaları için, app-server hesap bildirmediğinde ve hâlâ OpenAI kimlik doğrulaması gerektirdiğinde önce CODEX_API_KEY, sonra OPENAI_API_KEY.

Bu, gateway işleminin doğrudan OpenAI modelleri veya embeddings için ayrıca OPENAI_API_KEY değerine sahip olması nedeniyle yerel bir ChatGPT/Codex abonelik oturumunun değiştirilmediği anlamına gelir. Env API anahtarı yedeği yalnızca yerel stdio hesapsız yoludur; WebSocket app-server bağlantılarına gönderilmez. Abonelik tarzı bir Codex profili seçildiğinde, OpenClaw ayrıca CODEX_API_KEY ve OPENAI_API_KEY değerlerini oluşturulan stdio app-server alt sürecinin dışında tutar ve seçili kimlik bilgilerini app-server login RPC üzerinden gönderir.

# Görsel oluşturma

Pakete dahil openai Plugin'i, image_generate aracı üzerinden görsel oluşturmayı kaydeder. Aynı openai/gpt-image-2 model ref'i üzerinden hem OpenAI API anahtarlı görsel oluşturmayı hem de Codex OAuth görsel oluşturmayı destekler.

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}

gpt-image-2, hem OpenAI metinden görsele oluşturma hem de görsel düzenleme için varsayılandır. gpt-image-1.5, gpt-image-1 ve gpt-image-1-mini açık model geçersiz kılmaları olarak kullanılabilir kalır. Şeffaf arka planlı PNG/WebP çıktısı için openai/gpt-image-1.5 kullanın; geçerli gpt-image-2 API'si background: "transparent" değerini reddeder.

Şeffaf arka plan isteği için ajanlar image_generate aracını model: "openai/gpt-image-1.5", outputFormat: "png" veya "webp" ve background: "transparent" ile çağırmalıdır; eski openai.background sağlayıcı seçeneği hâlâ kabul edilir. OpenClaw ayrıca varsayılan openai/gpt-image-2 şeffaf isteklerini gpt-image-1.5 olarak yeniden yazarak genel OpenAI ve OpenAI Codex OAuth rotalarını korur; Azure ve özel OpenAI uyumlu uç noktalar yapılandırılmış dağıtım/model adlarını korur.

Aynı ayar headless CLI çalıştırmaları için de sunulur:

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

Bir girdi dosyasından başlarken openclaw infer image edit ile aynı --output-format ve --background bayraklarını kullanın. --openai-background, OpenAI'ye özgü alias olarak kullanılabilir kalır.

Codex OAuth kurulumları için aynı openai/gpt-image-2 ref'ini koruyun. Bir openai-codex OAuth profili yapılandırıldığında, OpenClaw depolanan OAuth erişim token'ını çözer ve görsel isteklerini Codex Responses backend üzerinden gönderir. Bu istek için önce OPENAI_API_KEY denemez veya sessizce bir API anahtarına geri dönmez. Bunun yerine doğrudan OpenAI Images API rotasını istediğinizde models.providers.openai değerini bir API anahtarı, özel base URL veya Azure endpoint ile açıkça yapılandırın. Bu özel görsel endpoint güvenilir bir LAN/özel adresteyse, ayrıca browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ayarlayın; bu opt-in mevcut olmadıkça OpenClaw özel/dahili OpenAI uyumlu görsel endpoint'leri engelli tutar.

Oluştur:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

Şeffaf PNG oluştur:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Düzenle:

/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

# Video oluşturma

Pakete dahil openai Plugin'i, video_generate aracı üzerinden video oluşturmayı kaydeder.

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

# GPT-5 prompt katkısı

OpenClaw, sağlayıcılar genelindeki GPT-5-family çalıştırmaları için paylaşılan bir GPT-5 prompt katkısı ekler. Model kimliğine göre uygulanır; bu nedenle openai/gpt-5.5, openai-codex/gpt-5.5 gibi eski onarım öncesi ref'ler, openrouter/openai/gpt-5.5, opencode/gpt-5.5 ve diğer uyumlu GPT-5 ref'leri aynı katmanı alır. Eski GPT-4.x modelleri almaz.

Pakete dahil yerel Codex koşum takımı, Codex app-server geliştirici talimatları üzerinden aynı GPT-5 davranışını ve Heartbeat katmanını kullanır; bu nedenle agentRuntime.id: "codex" üzerinden zorlanan openai/gpt-5.x oturumları, koşum takımı prompt'unun geri kalanına Codex sahip olsa bile aynı takip ve proaktif Heartbeat rehberliğini korur.

GPT-5 katkısı; persona kalıcılığı, yürütme güvenliği, araç disiplini, çıktı biçimi, tamamlama kontrolleri ve doğrulama için etiketli bir davranış sözleşmesi ekler. Kanala özgü yanıt ve sessiz mesaj davranışı, paylaşılan OpenClaw sistem isteminde ve giden teslim politikalarında kalır. GPT-5 rehberliği, eşleşen modeller için her zaman etkindir. Dostça etkileşim stili katmanı ayrı ve yapılandırılabilirdir.

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

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

# Ses ve konuşma

{
  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 uç noktaları

Paketlenen openai sağlayıcısı, temel URL'yi geçersiz kılarak görüntü oluşturma için bir Azure OpenAI kaynağını hedefleyebilir. Görüntü oluşturma yolunda OpenClaw, models.providers.openai.baseUrl üzerindeki Azure ana makine adlarını algılar ve otomatik olarak Azure'un istek biçimine geçer.

Azure OpenAI'ı şu durumlarda kullanın:

• Zaten bir Azure OpenAI aboneliğiniz, kotanız veya kurumsal anlaşmanız varsa
• Azure'un sağladığı bölgesel veri yerleşimi veya uyumluluk denetimlerine ihtiyacınız varsa
• Trafiği mevcut bir Azure kiracılığı içinde tutmak istiyorsanız

# Yapılandırma

Paketlenen openai sağlayıcısı üzerinden Azure görüntü oluşturma için models.providers.openai.baseUrl değerini Azure kaynağınıza yönlendirin ve apiKey değerini Azure OpenAI anahtarına ayarlayın (OpenAI Platform anahtarı değil):

{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}

OpenClaw, Azure görüntü oluşturma rotası için şu Azure ana makine son eklerini tanır:

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

Tanınan bir Azure ana makinesindeki görüntü oluşturma istekleri için OpenClaw:

• Authorization: Bearer yerine api-key üst bilgisini gönderir
• Dağıtım kapsamlı yolları kullanır (/openai/deployments/{deployment}/...)
• Her isteğe ?api-version=... ekler
• Azure görüntü oluşturma çağrıları için 600 sn varsayılan istek zaman aşımı kullanır. Çağrı başına timeoutMs değerleri yine de bu varsayılanı geçersiz kılar.

Diğer temel URL'ler (genel OpenAI, OpenAI uyumlu proxy'ler) standart OpenAI görüntü isteği biçimini korur.

# API sürümü

Azure görüntü oluşturma yolu için belirli bir Azure önizleme veya GA sürümünü sabitlemek üzere AZURE_OPENAI_API_VERSION ayarlayın:

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

Değişken ayarlanmamışsa varsayılan 2024-12-01-preview olur.

# Model adları dağıtım adlarıdır

Azure OpenAI, modelleri dağıtımlara bağlar. Paketlenen openai sağlayıcısı üzerinden yönlendirilen Azure görüntü oluşturma istekleri için OpenClaw'daki model alanı, genel OpenAI model kimliği değil, Azure portalında yapılandırdığınız Azure dağıtım adı olmalıdır.

gpt-image-2 sunan gpt-image-2-prod adlı bir dağıtım oluşturursanız:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

Aynı dağıtım adı kuralı, paketlenen openai sağlayıcısı üzerinden yönlendirilen görüntü oluşturma çağrıları için geçerlidir.

# Bölgesel kullanılabilirlik

Azure görüntü oluşturma şu anda yalnızca belirli bölgelerin bir alt kümesinde kullanılabilir (örneğin eastus2, swedencentral, polandcentral, westus3, uaenorth). Dağıtım oluşturmadan önce Microsoft'un güncel bölge listesini kontrol edin ve belirli modelin bölgenizde sunulduğunu doğrulayın.

# Parametre farkları

Azure OpenAI ve genel OpenAI her zaman aynı görüntü parametrelerini kabul etmez. Azure, genel OpenAI'ın izin verdiği seçenekleri reddedebilir (örneğin gpt-image-2 üzerinde belirli background değerleri) veya bunları yalnızca belirli model sürümlerinde sunabilir. Bu farklar Azure'dan ve temel modelden kaynaklanır, OpenClaw'dan değil. Bir Azure isteği doğrulama hatasıyla başarısız olursa, belirli dağıtımınız ve API sürümünüz tarafından desteklenen parametre kümesini Azure portalında kontrol edin.

# Gelişmiş yapılandırma

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

# İlgili