OpenAI

OpenAI, GPT modelleri için geliştirici API'leri sağlar ve Codex de OpenAI'nin Codex istemcileri üzerinden ChatGPT planına dahil bir kodlama ajanı olarak 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 dışı OpenAI yüzeyleri için kullanılabilir kalır.

• Ajan modelleri - Codex çalışma zamanı üzerinden openai/* modelleri; ChatGPT/Codex abonelik kullanımı için Codex kimlik doğrulamasıyla oturum açın veya bilinçli olarak API anahtarı kimlik doğrulaması istediğinizde Codex uyumlu bir OpenAI API anahtarı yedeği yapılandırın.
• Ajan dışı OpenAI API'leri - OPENAI_API_KEY veya OpenAI API anahtarı onboarding ü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/* artı Codex çalışma zamanı olacak şekilde onarılır.

OpenAI, OpenClaw gibi harici araç 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 bilinçli olarak openai/* model referansları içerebileceği, kimlik doğrulama profillerinin ise hâlâ Codex uyumlu kimlik bilgilerini gösterebileceği anlamına gelir. Yeni yapılandırmalar için auth.order.openai tercih edin; mevcut openai-codex:* profilleri ve auth.order.openai-codex desteklenmeye devam eder. openclaw doctor --fix, eski openai-codex/* model referanslarını standart OpenAI model rotasına yeniden yazar.

OpenClaw özellik kapsamı

Bellek embeddings

OpenClaw, memory_search indeksleme ve sorgu embeddings için OpenAI'yi veya OpenAI uyumlu bir embedding endpoint'ini kullanabilir:

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

Asimetrik embedding etiketleri gerektiren OpenAI uyumlu endpoint'ler 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; indekslenen bellek parçaları ve toplu indeksleme 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" },    },  },}

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

Yerel Codex app-server kimlik doğrulaması

Yerel Codex app-server düzeneği openai/* model başvurularını ve atlanmış çalışma zamanı yapılandırmasını veya sağlayıcı/model 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. Ajan için sıralı OpenAI kimlik doğrulama profilleri, tercihen auth.order.openai altında. Mevcut openai-codex:* profilleri ve auth.order.openai-codex eski kurulumlar için geçerli kalır.
2. App-server'ın mevcut hesabı, örneğin yerel Codex CLI ChatGPT oturumu.
3. Yalnızca yerel stdio app-server başlatmaları için, app-server hesap olmadığını bildirip hâlâ OpenAI kimlik doğrulaması gerektirdiğinde CODEX_API_KEY, ardından OPENAI_API_KEY.

Bu, Gateway sürecinde doğrudan OpenAI modelleri veya embedding'ler için OPENAI_API_KEY de var diye yerel ChatGPT/Codex abonelik oturumunun değiştirilmediği anlamına gelir. Env API anahtarı fallback'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. Bu abonelik profili bir Codex kullanım sınırı tarafından engellendiğinde, OpenClaw seçili modeli değiştirmeden veya Codex düzeneğinden çıkmadan sıradaki openai:* API anahtarı profiline dönebilir. Abonelik sıfırlama zamanı geçtiğinde, abonelik profili yeniden uygun olur.

Görsel üretimi

Paketle gelen openai Plugin'i, image_generate aracı üzerinden görsel üretimini kaydeder. Hem OpenAI API anahtarlı görsel üretimini hem de aynı openai/gpt-image-2 model başvurusu üzerinden Codex OAuth görsel üretimini destekler.

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

gpt-image-2, hem OpenAI metinden görsel üretimi 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; mevcut 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 herkese açık OpenAI ve OpenAI Codex OAuth rotalarını korur; Azure ve özel OpenAI uyumlu uç noktalar yapılandırılmış deployment/model adlarını korur.

Aynı ayar başsız 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'a özgü alias olarak kullanılabilir kalır.

Codex OAuth kurulumları için aynı openai/gpt-image-2 başvurusunu 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'i üzerinden gönderir. Bu istek için önce OPENAI_API_KEY denemez veya sessizce bir API anahtarına fallback yapılmaz. Bunun yerine doğrudan OpenAI Images API rotasını istediğinizde models.providers.openai değerini bir API anahtarı, özel base URL veya Azure uç noktasıyla açıkça yapılandırın. Bu özel görsel uç noktası güvenilir bir LAN/özel adresteyse ayrıca browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ayarlayın; OpenClaw bu opt-in mevcut olmadıkça özel/dahili OpenAI uyumlu görsel uç noktalarını engellenmiş tutar.

Üret:

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

Şeffaf PNG üret:

/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 üretimi

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

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

GPT-5 istem katkısı

OpenClaw, sağlayıcılar genelinde GPT-5 ailesi çalıştırmaları için paylaşılan bir GPT-5 istem 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 referanslar, openrouter/openai/gpt-5.5, opencode/gpt-5.5 ve diğer uyumlu GPT-5 referansları aynı katmanı alır. Daha eski GPT-4.x modelleri almaz.

Birlikte gelen yerel Codex harness, Codex app-server geliştirici yönergeleri üzerinden aynı GPT-5 davranışını ve heartbeat katmanını kullanır; bu nedenle Codex üzerinden yönlendirilen openai/gpt-5.x oturumları, harness isteminin geri kalanını Codex yönetse de aynı takip ve proaktif heartbeat rehberliğini korur.

GPT-5 katkısı; persona sürekliliği, 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 politikasında kalır. GPT-5 rehberliği, eşleşen modeller için her zaman etkindir. Dostane etkileşim stili katmanı ayrıdır ve yapılandırılabilir.

{  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ı

Birlikte gelen openai sağlayıcısı, temel URL'yi geçersiz kılarak görüntü üretimi için bir Azure OpenAI kaynağını hedefleyebilir. Görüntü üretimi 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 kontrollerine ihtiyacınız varsa
• Trafiği mevcut bir Azure kiracılığı içinde tutmak istiyorsanız

Yapılandırma

Birlikte gelen openai sağlayıcısı üzerinden Azure görüntü üretimi için models.providers.openai.baseUrl değerini Azure kaynağınıza yönlendirin ve apiKey değerini Azure OpenAI anahtarı olarak 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ü üretimi rotası için şu Azure ana makine soneklerini tanır:

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

Tanınan bir Azure ana makinesindeki görüntü üretimi isteklerinde OpenClaw:

• Authorization: Bearer yerine api-key üst bilgisini gönderir
• Dağıtım kapsamlı yolları (/openai/deployments/{deployment}/...) kullanır
• Her isteğe ?api-version=... ekler
• Azure görüntü üretimi çağrıları için varsayılan 600 sn 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 değerini ayarlayın:

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

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

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

Azure OpenAI, modelleri dağıtımlara bağlar. Paketle gelen openai sağlayıcısı üzerinden yönlendirilen Azure görüntü oluşturma istekleri için OpenClaw içindeki 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ı, paketle gelen openai sağlayıcısı üzerinden yönlendirilen görüntü oluşturma çağrıları için de 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). Bir 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 farklılıkları

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 OpenClaw'dan değil, Azure'dan ve altta yatan modelden kaynaklanır. 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" },        },      },    },  },}

{  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