Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenAI menyediakan API pengembang untuk model GPT, dan Codex juga tersedia sebagai agen coding paket ChatGPT melalui klien Codex milik OpenAI. OpenClaw menjaga permukaan tersebut tetap terpisah agar konfigurasi tetap dapat diprediksi. OpenClaw menggunakan openai/* sebagai rute model OpenAI kanonis. Giliran agen tertanam pada model OpenAI berjalan melalui runtime server aplikasi Codex native secara default; autentikasi kunci API OpenAI langsung tetap tersedia untuk permukaan OpenAI non-agen seperti gambar, embeddings, speech, dan realtime.
  • Model agen - model openai/* melalui runtime Codex; masuk dengan autentikasi Codex untuk penggunaan langganan ChatGPT/Codex, atau konfigurasikan cadangan kunci API OpenAI yang kompatibel dengan Codex saat Anda sengaja menginginkan autentikasi kunci API.
  • API OpenAI non-agen - akses OpenAI Platform langsung dengan penagihan berbasis penggunaan melalui OPENAI_API_KEY atau onboarding kunci API OpenAI.
  • Konfigurasi lama - ref model openai-codex/* diperbaiki oleh openclaw doctor --fix menjadi openai/* plus runtime Codex.
OpenAI secara eksplisit mendukung penggunaan OAuth langganan dalam alat dan alur kerja eksternal seperti OpenClaw. Provider, model, runtime, dan channel adalah lapisan yang terpisah. Jika label-label tersebut tercampur, baca Runtime agen sebelum mengubah konfigurasi.

​
Pilihan cepat

TujuanGunakanCatatan
Langganan ChatGPT/Codex dengan runtime Codex nativeopenai/gpt-5.5Penyiapan agen OpenAI default. Masuk dengan autentikasi Codex.
Penagihan kunci API langsung untuk model agenopenai/gpt-5.5 plus profil kunci API yang kompatibel dengan CodexGunakan auth.order.openai untuk menempatkan cadangan setelah autentikasi langganan.
Penagihan kunci API langsung melalui PI eksplisitopenai/gpt-5.5 plus runtime provider/model piPilih profil kunci API openai normal.
Alias API ChatGPT Instant terbaruopenai/chat-latestHanya kunci API langsung. Alias bergerak untuk eksperimen, bukan default.
Autentikasi langganan ChatGPT/Codex melalui PI eksplisitopenai/gpt-5.5 plus runtime provider/model piPilih profil autentikasi openai-codex untuk rute kompatibilitas.
Pembuatan atau penyuntingan gambaropenai/gpt-image-2Berfungsi dengan OPENAI_API_KEY atau OpenAI Codex OAuth.
Gambar latar belakang transparanopenai/gpt-image-1.5Gunakan outputFormat=png atau webp dan openai.background=transparent.

​
Peta penamaan

Nama-namanya mirip tetapi tidak dapat dipertukarkan:
Nama yang Anda lihatLapisanMakna
openaiPrefiks providerRute model OpenAI kanonis; giliran agen menggunakan runtime Codex.
openai-codexPrefiks autentikasi/profil lamaNamespace profil langganan/OAuth OpenAI Codex lama. Profil yang ada dan auth.order.openai-codex tetap berfungsi.
Plugin codexPluginPlugin OpenClaw bawaan yang menyediakan runtime server aplikasi Codex native dan kontrol chat /codex.
provider/model agentRuntime.id: codexRuntime agenMemaksa harness server aplikasi Codex native untuk giliran tertanam yang cocok.
/codex ...Set perintah chatMengikat/mengontrol thread server aplikasi Codex dari percakapan.
runtime: "acp", agentId: "codex"Rute sesi ACPJalur fallback eksplisit yang menjalankan Codex melalui ACP/acpx.
Ini berarti konfigurasi dapat dengan sengaja berisi ref model openai/* sementara profil autentikasi masih menunjuk ke kredensial yang kompatibel dengan Codex. Lebih utamakan auth.order.openai untuk konfigurasi baru; profil openai-codex:* yang ada dan auth.order.openai-codex tetap didukung. openclaw doctor --fix menulis ulang ref model lama openai-codex/* ke rute model OpenAI kanonis.
GPT-5.5 tersedia melalui akses kunci API OpenAI Platform langsung dan rute langganan/OAuth. Untuk langganan ChatGPT/Codex plus eksekusi Codex native, gunakan openai/gpt-5.5; konfigurasi runtime yang tidak disetel kini memilih harness Codex untuk giliran agen OpenAI. Gunakan profil kunci API OpenAI hanya saat Anda menginginkan autentikasi kunci API langsung untuk model agen OpenAI.
Giliran model agen OpenAI memerlukan Plugin server aplikasi Codex bawaan. Konfigurasi runtime PI eksplisit tetap tersedia sebagai rute kompatibilitas opt-in. Saat PI dipilih secara eksplisit dengan profil autentikasi openai-codex, OpenClaw menjaga ref model publik sebagai openai/* dan merutekan PI secara internal melalui transport autentikasi Codex lama. Jalankan openclaw doctor --fix untuk memperbaiki ref model openai-codex/* yang kedaluwarsa atau pin sesi PI lama yang tidak berasal dari konfigurasi runtime eksplisit.

​
Cakupan fitur OpenClaw

Kemampuan OpenAIPermukaan OpenClawStatus
Chat / ResponsesProvider model openai/<model>Ya
Model langganan Codexopenai/<model> dengan OAuth openai-codexYa
Ref model Codex lamaopenai-codex/<model>Diperbaiki oleh doctor ke openai/<model>
Harness server aplikasi Codexopenai/<model> dengan runtime dihilangkan atau provider/model agentRuntime.id: codexYa
Pencarian web sisi serverAlat OpenAI Responses nativeYa, saat pencarian web diaktifkan dan tidak ada provider yang dipin
Gambarimage_generateYa
Videovideo_generateYa
Teks-ke-speechmessages.tts.provider: "openai" / ttsYa
Speech-ke-teks batchtools.media.audio / pemahaman mediaYa
Speech-ke-teks streamingVoice Call streaming.provider: "openai"Ya
Suara realtimeVoice Call realtime.provider: "openai" / Control UI TalkYa
Embeddingsprovider embedding memoriYa

​
Embeddings memori

OpenClaw dapat menggunakan OpenAI, atau endpoint embedding yang kompatibel dengan OpenAI, untuk pengindeksan memory_search dan embeddings kueri: 
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}
Untuk endpoint yang kompatibel dengan OpenAI yang memerlukan label embedding asimetris, setel queryInputType dan documentInputType di bawah memorySearch. OpenClaw meneruskannya sebagai field permintaan input_type khusus provider: embeddings kueri menggunakan queryInputType; potongan memori terindeks dan pengindeksan batch menggunakan documentInputType. Lihat Referensi konfigurasi memori untuk contoh lengkapnya.

​
Memulai

Pilih metode autentikasi pilihan Anda dan ikuti langkah penyiapannya.
Paling cocok untuk: akses API langsung dan penagihan berbasis penggunaan.
1

Dapatkan kunci API Anda

Buat atau salin kunci API dari dasbor OpenAI Platform.
2

Jalankan onboarding

openclaw onboard --auth-choice openai-api-key
Atau teruskan kuncinya secara langsung:
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

Verifikasi model tersedia

openclaw models list --provider openai

​
Ringkasan rute

Ref modelKonfigurasi runtimeRuteAutentikasi
openai/gpt-5.5dihilangkan / provider/model agentRuntime.id: "codex"Harness server aplikasi CodexProfil OpenAI yang kompatibel dengan Codex
openai/gpt-5.4-minidihilangkan / provider/model agentRuntime.id: "codex"Harness server aplikasi CodexProfil OpenAI yang kompatibel dengan Codex
openai/gpt-5.5provider/model agentRuntime.id: "pi"Runtime tertanam PIProfil openai atau profil openai-codex yang dipilih
Model agen openai/* menggunakan harness server aplikasi Codex. Untuk menggunakan autentikasi kunci API bagi model agen, buat profil kunci API yang kompatibel dengan Codex dan urutkan dengan auth.order.openai; OPENAI_API_KEY tetap menjadi fallback langsung untuk permukaan API OpenAI non-agen. Entri auth.order.openai-codex yang lebih lama tetap berfungsi.

​
Contoh konfigurasi

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
Untuk mencoba model Instant ChatGPT saat ini dari OpenAI API, setel model ke openai/chat-latest:
{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}
chat-latest adalah alias bergerak. OpenAI mendokumentasikannya sebagai model Instant terbaru yang digunakan di ChatGPT dan merekomendasikan gpt-5.5 untuk penggunaan API produksi, jadi pertahankan openai/gpt-5.5 sebagai default stabil kecuali Anda secara eksplisit menginginkan perilaku alias tersebut. Alias saat ini hanya menerima verbositas teks medium, sehingga OpenClaw menormalisasi override verbositas teks OpenAI yang tidak kompatibel untuk model ini.
OpenClaw tidak mengekspos openai/gpt-5.3-codex-spark. Permintaan OpenAI API langsung menolak model tersebut, dan katalog Codex saat ini juga tidak mengeksposnya.

​
Auth app-server Codex native

Harness app-server Codex native menggunakan ref model openai/* plus konfigurasi runtime yang dihilangkan atau provider/model agentRuntime.id: "codex", tetapi auth-nya tetap berbasis akun. OpenClaw memilih auth dalam urutan ini:
  1. Profil auth OpenAI berurutan untuk agen, sebaiknya di bawah auth.order.openai. Profil openai-codex:* yang sudah ada dan auth.order.openai-codex tetap valid untuk instalasi yang lebih lama.
  2. Akun app-server yang sudah ada, seperti masuk ChatGPT CLI Codex lokal.
  3. Hanya untuk peluncuran app-server stdio lokal, CODEX_API_KEY, lalu OPENAI_API_KEY, saat app-server melaporkan tidak ada akun dan masih memerlukan auth OpenAI.
Artinya, masuk langganan ChatGPT/Codex lokal tidak diganti hanya karena proses gateway juga memiliki OPENAI_API_KEY untuk model OpenAI langsung atau embedding. Fallback kunci API env hanya jalur lokal stdio tanpa akun; fallback itu tidak dikirim ke koneksi app-server WebSocket. Saat profil Codex bergaya langganan dipilih, OpenClaw juga menjauhkan CODEX_API_KEY dan OPENAI_API_KEY dari child app-server stdio yang di-spawn dan mengirim kredensial terpilih melalui RPC login app-server. Saat profil langganan tersebut diblokir oleh batas penggunaan Codex, OpenClaw dapat berotasi ke profil kunci API openai:* berurutan berikutnya tanpa mengubah model terpilih atau keluar dari harness Codex. Setelah waktu reset langganan berlalu, profil langganan memenuhi syarat lagi.

​
Pembuatan gambar

Plugin openai bawaan mendaftarkan pembuatan gambar melalui alat image_generate. Plugin ini mendukung pembuatan gambar dengan kunci API OpenAI dan pembuatan gambar OAuth Codex melalui ref model openai/gpt-image-2 yang sama.
KemampuanKunci API OpenAIOAuth Codex
Ref modelopenai/gpt-image-2openai/gpt-image-2
AuthOPENAI_API_KEYMasuk OAuth OpenAI Codex
TransportAPI Gambar OpenAIBackend Respons Codex
Maks gambar per permintaan44
Mode editDiaktifkan (hingga 5 gambar referensi)Diaktifkan (hingga 5 gambar referensi)
Penimpaan ukuranDidukung, termasuk ukuran 2K/4KDidukung, termasuk ukuran 2K/4K
Rasio aspek / resolusiTidak diteruskan ke API Gambar OpenAIDipetakan ke ukuran yang didukung saat aman
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}
Lihat Pembuatan Gambar untuk parameter alat bersama, pemilihan provider, dan perilaku failover.
gpt-image-2 adalah default untuk pembuatan gambar dari teks OpenAI dan pengeditan gambar. gpt-image-1.5, gpt-image-1, dan gpt-image-1-mini tetap dapat digunakan sebagai penimpaan model eksplisit. Gunakan openai/gpt-image-1.5 untuk keluaran PNG/WebP dengan latar belakang transparan; API gpt-image-2 saat ini menolak background: "transparent". Untuk permintaan latar belakang transparan, agen harus memanggil image_generate dengan model: "openai/gpt-image-1.5", outputFormat: "png" atau "webp", dan background: "transparent"; opsi provider openai.background yang lebih lama tetap diterima. OpenClaw juga melindungi rute publik OpenAI dan OAuth OpenAI Codex dengan menulis ulang permintaan transparan default openai/gpt-image-2 ke gpt-image-1.5; endpoint Azure dan OpenAI-compatible kustom mempertahankan nama deployment/model yang dikonfigurasi. Pengaturan yang sama diekspos untuk eksekusi CLI headless: 
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
Gunakan flag --output-format dan --background yang sama dengan openclaw infer image edit saat memulai dari file input. --openai-background tetap tersedia sebagai alias khusus OpenAI. Untuk instalasi OAuth Codex, pertahankan ref openai/gpt-image-2 yang sama. Saat profil OAuth openai-codex dikonfigurasi, OpenClaw menyelesaikan token akses OAuth tersimpan tersebut dan mengirim permintaan gambar melalui backend Respons Codex. OpenClaw tidak mencoba OPENAI_API_KEY terlebih dahulu atau diam-diam fallback ke kunci API untuk permintaan tersebut. Konfigurasikan models.providers.openai secara eksplisit dengan kunci API, URL dasar kustom, atau endpoint Azure saat Anda menginginkan rute API Gambar OpenAI langsung sebagai gantinya. Jika endpoint gambar kustom tersebut berada di alamat LAN/privat tepercaya, atur juga browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw tetap memblokir endpoint gambar OpenAI-compatible privat/internal kecuali opt-in ini ada. Buat: 
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
Buat PNG transparan: 
/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
Edit: 
/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

​
Pembuatan video

Plugin openai bawaan mendaftarkan pembuatan video melalui tool video_generate.
KapabilitasNilai
Model defaultopenai/sora-2
ModeTeks-ke-video, gambar-ke-video, pengeditan video tunggal
Input referensi1 gambar atau 1 video
Override ukuranDidukung
Override lainaspectRatio, resolution, audio, watermark diabaikan dengan peringatan tool
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
Lihat Pembuatan Video untuk parameter tool bersama, pemilihan penyedia, dan perilaku failover.

​
Kontribusi prompt GPT-5

OpenClaw menambahkan kontribusi prompt GPT-5 bersama untuk eksekusi keluarga GPT-5 lintas penyedia. Ini diterapkan berdasarkan id model, sehingga openai/gpt-5.5, referensi lama sebelum perbaikan seperti openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5, dan referensi GPT-5 kompatibel lainnya menerima overlay yang sama. Model GPT-4.x yang lebih lama tidak. Harness Codex native bawaan menggunakan perilaku GPT-5 yang sama dan overlay Heartbeat melalui instruksi developer server aplikasi Codex, sehingga sesi openai/gpt-5.x yang dirutekan melalui Codex mempertahankan panduan tindak lanjut dan Heartbeat proaktif yang sama meskipun Codex memiliki sisa prompt harness. Kontribusi GPT-5 menambahkan kontrak perilaku bertag untuk persistensi persona, keselamatan eksekusi, disiplin tool, bentuk output, pemeriksaan penyelesaian, dan verifikasi. Perilaku balasan khusus channel dan pesan senyap tetap berada di prompt sistem OpenClaw bersama dan kebijakan pengiriman keluar. Panduan GPT-5 selalu diaktifkan untuk model yang cocok. Lapisan gaya interaksi ramah terpisah dan dapat dikonfigurasi.
NilaiEfek
"friendly" (default)Mengaktifkan lapisan gaya interaksi ramah
"on"Alias untuk "friendly"
"off"Menonaktifkan hanya lapisan gaya ramah
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}
Nilai tidak peka huruf besar-kecil saat runtime, sehingga "Off" dan "off" sama-sama menonaktifkan lapisan gaya ramah.
plugins.entries.openai.config.personality lama masih dibaca sebagai fallback kompatibilitas saat pengaturan bersama agents.defaults.promptOverlays.gpt5.personality belum disetel.

​
Suara dan ucapan

Plugin openai bawaan mendaftarkan sintesis ucapan untuk surface messages.tts.
PengaturanJalur konfigurasiDefault
Modelmessages.tts.providers.openai.modelgpt-4o-mini-tts
Suaramessages.tts.providers.openai.voicecoral
Kecepatanmessages.tts.providers.openai.speed(belum disetel)
Instruksimessages.tts.providers.openai.instructions(belum disetel, hanya gpt-4o-mini-tts)
Formatmessages.tts.providers.openai.responseFormatopus untuk catatan suara, mp3 untuk file
Kunci APImessages.tts.providers.openai.apiKeyBeralih kembali ke OPENAI_API_KEY
URL dasarmessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
Isi tambahanmessages.tts.providers.openai.extraBody / extra_body(belum disetel)
Model yang tersedia: gpt-4o-mini-tts, tts-1, tts-1-hd. Suara yang tersedia: alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.extraBody digabungkan ke JSON permintaan /audio/speech setelah field yang dihasilkan OpenClaw, jadi gunakan untuk endpoint yang kompatibel dengan OpenAI yang memerlukan kunci tambahan seperti lang. Kunci prototype diabaikan.
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
Setel OPENAI_TTS_BASE_URL untuk meng-override URL dasar TTS tanpa memengaruhi endpoint API chat. TTS OpenAI masih dikonfigurasi melalui kunci API; untuk balasan bicara langsung khusus OAuth, gunakan jalur suara Realtime, bukan ucapan STT -> TTS mode agen.
Plugin openai bawaan mendaftarkan ucapan-ke-teks batch melalui surface transkripsi pemahaman-media OpenClaw.
  • Model default: gpt-4o-transcribe
  • Endpoint: REST OpenAI /v1/audio/transcriptions
  • Jalur input: unggahan file audio multipart
  • Didukung oleh OpenClaw di mana pun transkripsi audio masuk menggunakan tools.media.audio, termasuk segmen channel suara Discord dan lampiran audio channel
Untuk memaksa OpenAI bagi transkripsi audio masuk:
{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
Petunjuk bahasa dan prompt diteruskan ke OpenAI saat disediakan oleh konfigurasi media audio bersama atau permintaan transkripsi per panggilan.
Plugin openai bawaan mendaftarkan transkripsi waktu nyata untuk Plugin Voice Call.
PengaturanJalur configDefault
Modelplugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
Bahasa...openai.language(belum disetel)
Prompt...openai.prompt(belum disetel)
Durasi hening...openai.silenceDurationMs800
Ambang VAD...openai.vadThreshold0.5
Auth...openai.apiKey, OPENAI_API_KEY, atau OAuth openai-codexKunci API terhubung langsung; OAuth membuat client secret transkripsi Realtime
Menggunakan koneksi WebSocket ke wss://api.openai.com/v1/realtime dengan audio G.711 u-law (g711_ulaw / audio/pcmu). Ketika hanya OAuth openai-codex yang dikonfigurasi, Gateway membuat client secret transkripsi Realtime sementara sebelum membuka WebSocket. Penyedia streaming ini ditujukan untuk jalur transkripsi waktu nyata Voice Call; voice Discord saat ini merekam segmen pendek dan menggunakan jalur transkripsi batch tools.media.audio sebagai gantinya.
Plugin openai bawaan mendaftarkan suara waktu nyata untuk Plugin Voice Call.
PengaturanJalur configDefault
Modelplugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime-2
Suara...openai.voicealloy
Temperature (jembatan deployment Azure)...openai.temperature0.8
Ambang VAD...openai.vadThreshold0.5
Durasi hening...openai.silenceDurationMs500
Padding prefiks...openai.prefixPaddingMs300
Upaya reasoning...openai.reasoningEffort(belum disetel)
Auth...openai.apiKey, OPENAI_API_KEY, atau OAuth openai-codexBrowser Talk dan jembatan backend non-Azure dapat menggunakan OAuth Codex
Suara Realtime bawaan yang tersedia untuk gpt-realtime-2: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. OpenAI merekomendasikan marin dan cedar untuk kualitas Realtime terbaik. Ini adalah rangkaian terpisah dari suara Text-to-speech di atas; jangan menganggap suara TTS seperti fable, nova, atau onyx valid untuk sesi Realtime.
Jembatan realtime OpenAI backend menggunakan bentuk sesi WebSocket Realtime GA, yang tidak menerima session.temperature. Deployment Azure OpenAI tetap tersedia melalui azureEndpoint dan azureDeployment serta mempertahankan bentuk sesi yang kompatibel dengan deployment. Mendukung pemanggilan tool dua arah dan audio G.711 u-law.
Suara Realtime dipilih ketika sesi dibuat. OpenAI mengizinkan sebagian besar field sesi diubah nanti, tetapi suara tidak dapat diubah setelah model menghasilkan audio dalam sesi tersebut. OpenClaw saat ini mengekspos id suara Realtime bawaan sebagai string.
Control UI Talk menggunakan sesi realtime browser OpenAI dengan client secret sementara yang dibuat oleh Gateway dan pertukaran SDP WebRTC browser langsung terhadap OpenAI Realtime API. Ketika tidak ada kunci API OpenAI langsung yang dikonfigurasi, Gateway dapat membuat client secret tersebut dengan profil OAuth openai-codex yang dipilih. Relay Gateway dan jembatan WebSocket realtime backend Voice Call menggunakan fallback OAuth yang sama untuk endpoint OpenAI native. Verifikasi live maintainer tersedia dengan OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts; leg OpenAI memverifikasi jembatan WebSocket backend dan pertukaran SDP WebRTC browser tanpa mencatat secret.

​
Endpoint Azure OpenAI

Penyedia openai bawaan dapat menargetkan resource Azure OpenAI untuk pembuatan gambar dengan menimpa URL dasar. Pada jalur pembuatan gambar, OpenClaw mendeteksi hostname Azure pada models.providers.openai.baseUrl dan beralih ke bentuk request Azure secara otomatis.
Suara waktu nyata menggunakan jalur konfigurasi terpisah (plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint) dan tidak terpengaruh oleh models.providers.openai.baseUrl. Lihat accordion Suara waktu nyata di bawah Suara dan speech untuk pengaturan Azure-nya.
Gunakan Azure OpenAI ketika:
  • Anda sudah memiliki langganan, kuota, atau perjanjian enterprise Azure OpenAI
  • Anda memerlukan residensi data regional atau kontrol kepatuhan yang disediakan Azure
  • Anda ingin mempertahankan traffic di dalam tenancy Azure yang sudah ada

​
Konfigurasi

Untuk pembuatan gambar Azure melalui penyedia openai bawaan, arahkan models.providers.openai.baseUrl ke resource Azure Anda dan setel apiKey ke kunci Azure OpenAI (bukan kunci OpenAI Platform): 
{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}
OpenClaw mengenali sufiks host Azure ini untuk rute pembuatan gambar Azure:
  • *.openai.azure.com
  • *.services.ai.azure.com
  • *.cognitiveservices.azure.com
Untuk request pembuatan gambar pada host Azure yang dikenali, OpenClaw:
  • Mengirim header api-key, bukan Authorization: Bearer
  • Menggunakan jalur dengan cakupan deployment (/openai/deployments/{deployment}/...)
  • Menambahkan ?api-version=... ke setiap request
  • Menggunakan timeout request default 600 dtk untuk panggilan pembuatan gambar Azure. Nilai timeoutMs per panggilan tetap menimpa default ini.
URL dasar lain (OpenAI publik, proxy yang kompatibel dengan OpenAI) mempertahankan bentuk request gambar OpenAI standar.
Routing Azure untuk jalur pembuatan gambar penyedia openai memerlukan OpenClaw 2026.4.22 atau yang lebih baru. Versi sebelumnya memperlakukan openai.baseUrl kustom seperti endpoint OpenAI publik dan akan gagal terhadap deployment gambar Azure.

​
Versi API

Tetapkan AZURE_OPENAI_API_VERSION untuk menyematkan versi pratinjau atau GA Azure tertentu untuk jalur pembuatan gambar Azure: 
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
Default-nya adalah 2024-12-01-preview ketika variabel tidak ditetapkan.

​
Nama model adalah nama deployment

Azure OpenAI mengikat model ke deployment. Untuk permintaan pembuatan gambar Azure yang dirutekan melalui penyedia openai bawaan, kolom model di OpenClaw harus berupa nama deployment Azure yang Anda konfigurasi di portal Azure, bukan id model OpenAI publik. Jika Anda membuat deployment bernama gpt-image-2-prod yang melayani gpt-image-2: 
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
Aturan nama deployment yang sama berlaku untuk panggilan pembuatan gambar yang dirutekan melalui penyedia openai bawaan.

​
Ketersediaan regional

Pembuatan gambar Azure saat ini hanya tersedia di sebagian region (misalnya eastus2, swedencentral, polandcentral, westus3, uaenorth). Periksa daftar region Microsoft terbaru sebelum membuat deployment, dan konfirmasikan bahwa model tertentu ditawarkan di region Anda.

​
Perbedaan parameter

Azure OpenAI dan OpenAI publik tidak selalu menerima parameter gambar yang sama. Azure mungkin menolak opsi yang diizinkan oleh OpenAI publik (misalnya nilai background tertentu pada gpt-image-2) atau mengeksposnya hanya pada versi model tertentu. Perbedaan ini berasal dari Azure dan model yang mendasarinya, bukan OpenClaw. Jika permintaan Azure gagal dengan kesalahan validasi, periksa kumpulan parameter yang didukung oleh deployment dan versi API spesifik Anda di portal Azure.
Azure OpenAI menggunakan transport native dan perilaku compat, tetapi tidak menerima header atribusi tersembunyi OpenClaw — lihat accordion Rute native vs kompatibel OpenAI di bawah Konfigurasi lanjutan.Untuk traffic chat atau Responses di Azure (di luar pembuatan gambar), gunakan alur onboarding atau konfigurasi penyedia Azure khusus — openai.baseUrl saja tidak mengambil bentuk API/auth Azure. Penyedia terpisah azure-openai-responses/* tersedia; lihat accordion Compaction sisi server di bawah.

​
Konfigurasi lanjutan

OpenClaw menggunakan WebSocket terlebih dahulu dengan fallback SSE ("auto") untuk openai/*.Dalam mode "auto", OpenClaw:
  • Mencoba ulang satu kegagalan WebSocket awal sebelum beralih ke SSE
  • Setelah kegagalan, menandai WebSocket sebagai terdegradasi selama ~60 detik dan menggunakan SSE selama masa pendinginan
  • Melampirkan header identitas sesi dan turn yang stabil untuk percobaan ulang dan koneksi ulang
  • Menormalkan penghitung penggunaan (input_tokens / prompt_tokens) di seluruh varian transport
NilaiPerilaku
"auto" (default)WebSocket terlebih dahulu, fallback SSE
"sse"Paksa hanya SSE
"websocket"Paksa hanya WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
Dokumentasi OpenAI terkait:
OpenClaw mengekspos toggle mode cepat bersama untuk openai/*:
  • Chat/UI: /fast status|on|off
  • Konfigurasi: agents.defaults.models["<provider>/<model>"].params.fastMode
Ketika diaktifkan, OpenClaw memetakan mode cepat ke pemrosesan prioritas OpenAI (service_tier = "priority"). Nilai service_tier yang ada dipertahankan, dan mode cepat tidak menulis ulang reasoning atau text.verbosity.
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
Override sesi mengalahkan konfigurasi. Menghapus override sesi di UI Sessions mengembalikan sesi ke default yang dikonfigurasi.
API OpenAI mengekspos pemrosesan prioritas melalui service_tier. Tetapkan per model di OpenClaw:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}
Nilai yang didukung: auto, default, flex, priority.
serviceTier hanya diteruskan ke endpoint OpenAI native (api.openai.com) dan endpoint Codex native (chatgpt.com/backend-api). Jika Anda merutekan salah satu penyedia melalui proxy, OpenClaw membiarkan service_tier tidak berubah.
Untuk model OpenAI Responses langsung (openai/* di api.openai.com), wrapper stream Pi-harness Plugin OpenAI mengaktifkan otomatis Compaction sisi server:
  • Memaksa store: true (kecuali compat model menetapkan supportsStore: false)
  • Menyuntikkan context_management: [{ type: "compaction", compact_threshold: ... }]
  • Default compact_threshold: 70% dari contextWindow (atau 80000 ketika tidak tersedia)
Ini berlaku untuk jalur harness Pi bawaan dan untuk hook penyedia OpenAI yang digunakan oleh run tersemat. Harness app-server Codex native mengelola konteksnya sendiri melalui Codex dan dikonfigurasi oleh rute agen default OpenAI atau kebijakan runtime penyedia/model.
Berguna untuk endpoint yang kompatibel seperti Azure OpenAI Responses:
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction hanya mengontrol penyuntikan context_management. Model OpenAI Responses langsung tetap memaksa store: true kecuali compat menetapkan supportsStore: false.
Untuk run keluarga GPT-5 pada openai/*, OpenClaw dapat menggunakan kontrak eksekusi tersemat yang lebih ketat:
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
Dengan strict-agentic, OpenClaw:
  • Tidak lagi memperlakukan turn yang hanya berisi rencana sebagai progres berhasil ketika aksi tool tersedia
  • Mencoba ulang turn dengan arahan untuk bertindak sekarang
  • Mengaktifkan otomatis update_plan untuk pekerjaan substansial
  • Menampilkan status diblokir eksplisit jika model terus merencanakan tanpa bertindak
Dicakup hanya untuk run keluarga GPT-5 OpenAI dan Codex. Penyedia lain dan keluarga model lama mempertahankan perilaku default.
OpenClaw memperlakukan endpoint OpenAI langsung, Codex, dan Azure OpenAI secara berbeda dari proxy /v1 generik yang kompatibel dengan OpenAI:Rute native (openai/*, Azure OpenAI):
  • Mempertahankan reasoning: { effort: "none" } hanya untuk model yang mendukung effort none OpenAI
  • Menghilangkan reasoning yang dinonaktifkan untuk model atau proxy yang menolak reasoning.effort: "none"
  • Menjadikan skema tool default ke mode ketat
  • Melampirkan header atribusi tersembunyi hanya pada host native terverifikasi
  • Mempertahankan pembentukan permintaan khusus OpenAI (service_tier, store, reasoning-compat, petunjuk prompt-cache)
Rute proxy/kompatibel:
  • Menggunakan perilaku compat yang lebih longgar
  • Menghapus store Completions dari payload openai-completions non-native
  • Menerima JSON pass-through params.extra_body/params.extraBody lanjutan untuk proxy Completions yang kompatibel dengan OpenAI
  • Menerima params.chat_template_kwargs untuk proxy Completions yang kompatibel dengan OpenAI seperti vLLM
  • Tidak memaksa skema tool ketat atau header khusus native
Azure OpenAI menggunakan transport native dan perilaku compat tetapi tidak menerima header atribusi tersembunyi.

​
Terkait

Pemilihan model

Memilih penyedia, ref model, dan perilaku failover.

Pembuatan gambar

Parameter tool gambar bersama dan pemilihan penyedia.

Pembuatan video

Parameter tool video bersama dan pemilihan penyedia.

OAuth dan auth

Detail auth dan aturan penggunaan ulang kredensial.