OpenAI

OpenClaw menggunakan satu id penyedia, openai, untuk autentikasi kunci API langsung dan autentikasi langganan ChatGPT/Codex. openai/* adalah rute model kanonis. Untuk giliran agen tertanam dengan kebijakan runtime yang tidak ditetapkan atau auto, fakta rute OpenAI menentukan apakah OpenClaw dapat memilih runtime server aplikasi Codex bawaan secara implisit. Prefiks openai/* saja tidak memilih runtime.

• Model agen - openai/* melalui runtime yang dipilih oleh konfigurasi agentRuntime eksplisit atau kebijakan rute implisit OpenAI. Masuk dengan autentikasi Codex untuk menggunakan langganan ChatGPT/Codex, atau konfigurasikan profil autentikasi kunci API jika Anda menginginkan penagihan berbasis kunci.
• API OpenAI non-agen - akses langsung ke OpenAI Platform, ditagih per penggunaan, melalui OPENAI_API_KEY atau profil autentikasi kunci API openai.
• Konfigurasi lama - referensi codex/* dan openai-codex/* diperbaiki menjadi openai/* ditambah agentRuntime.id: "codex" dengan cakupan model oleh openclaw doctor --fix.

OpenAI secara eksplisit mendukung penggunaan OAuth langganan dalam alat eksternal dan alur kerja seperti OpenClaw.

Pelacakan penggunaan dan biaya

OpenClaw memisahkan kuota langganan dan penagihan API Platform:

• OAuth ChatGPT/Codex menampilkan paket langganan, jendela kuota, dan saldo kredit.
• OPENAI_ADMIN_KEY menampilkan biaya organisasi dan penggunaan penyelesaian yang dilaporkan penyedia selama 30 hari di Penggunaan Control UI, termasuk pengeluaran harian, total permintaan/token, model teratas, dan kategori biaya.
• OPENAI_PROJECT_ID secara opsional membatasi riwayat Admin API ke satu proyek.
• OpenClaw tidak pernah mengirim OPENAI_API_KEY atau profil inferensi openai ke API organisasi; kredensial tersebut mungkin dimiliki oleh endpoint kustom, Azure, atau lokal agen.

Kunci Admin eksplisit lebih diprioritaskan daripada OAuth. Riwayat yang dilaporkan penyedia tidak digabungkan dengan perkiraan biaya turunan sesi OpenClaw; riwayat tersebut dapat mencakup aktivitas API dari klien lain dan penyesuaian penagihan di sisi penyedia.

Dokumentasi Dasbor Penggunaan API OpenAI menjelaskan persyaratan pemilik organisasi dan izin Dasbor Penggunaan eksplisit untuk data penggunaan.

Penyedia, model, runtime, dan saluran merupakan lapisan yang terpisah. Jika label tersebut tercampur, baca Runtime agen sebelum mengubah konfigurasi.

Pilihan cepat

Peta penamaan

Runtime agen implisit

Ketika kebijakan agentRuntime penyedia/model tidak ditetapkan atau auto, kebijakan rute milik penyedia OpenAI memilih runtime implisit berdasarkan endpoint dan adaptor efektif:

agentRuntime.id penyedia/model non-default yang eksplisit tetap menjadi acuan. Misalnya, agentRuntime.id: "openclaw" mempertahankan rute yang seharusnya memenuhi syarat Codex di OpenClaw, sedangkan agentRuntime.id: "codex" mewajibkan Codex dan gagal secara tertutup ketika rute efektif tidak dinyatakan kompatibel dengan Codex. Pemilihan runtime tidak mengubah jenis kredensial atau penagihan: autentikasi kunci API Platform dan autentikasi langganan ChatGPT/Codex tetap terpisah.

openclaw doctor --fix memigrasikan referensi model codex/* dan openai-codex/* lama, id profil autentikasi Codex lama, serta entri urutan autentikasi Codex lama ke rute kanonis openai. Referensi model yang dimigrasikan menerima agentRuntime.id: "codex" dengan cakupan model; gunakan auth.order.openai untuk konfigurasi urutan autentikasi baru.

Pratinjau terbatas GPT-5.6

OpenClaw mengenali id model openai/gpt-5.6-sol, openai/gpt-5.6-terra, dan openai/gpt-5.6-luna yang tepat. Ketiganya menyediakan penalaran xhigh dan max dalam katalog saat ini. OpenAI mendeskripsikan Sol sebagai tingkat unggulan, Terra sebagai tingkat seimbang, dan Luna sebagai tingkat cepat dengan biaya lebih rendah. Lihat pengumuman peluncuran GPT-5.6 dan panduan akses.

Dengan autentikasi kunci API OpenAI langsung, id openai/gpt-5.6 tanpa penentu adalah alias untuk Sol dan merupakan default penyiapan baru. Katalog Codex native tidak menerapkan alias API langsung tersebut di sisi klien; bergantung pada akses ruang kerja, katalog dapat menampilkan id Sol, Terra, dan Luna yang tepat. Oleh karena itu, penyiapan OAuth ChatGPT/Codex baru menggunakan openai/gpt-5.6-sol. Periksa akun saat ini dengan:

openclaw models list --provider openai

Akses organisasi API dan ruang kerja Codex dapat berbeda. Jika GPT-5.6 tidak tersedia, pilih GPT-5.5 secara eksplisit:

openclaw models set openai/gpt-5.5

OpenClaw menampilkan kesalahan akses dari hulu dan tidak mengganti pilihan GPT-5.6 dengan GPT-5.5 secara diam-diam.

Cakupan fitur OpenClaw

Embedding memori

OpenClaw dapat menggunakan OpenAI, atau endpoint embedding yang kompatibel dengan OpenAI, untuk pengindeksan memory_search dan embedding kueri:

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

Untuk endpoint yang kompatibel dengan OpenAI yang memerlukan label embedding asimetris, tetapkan queryInputType dan documentInputType di bawah memorySearch. OpenClaw meneruskannya sebagai bidang permintaan input_type khusus penyedia: embedding kueri menggunakan queryInputType; potongan memori terindeks dan pengindeksan batch menggunakan documentInputType. Lihat Referensi konfigurasi memori untuk contoh lengkap.

Memulai

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

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

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

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw 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

openclaw doctor --fixopenclaw config validate

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

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

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

Autentikasi app-server Codex native

Harness app-server Codex native menggunakan referensi model openai/* saat rute HTTPS resmi yang persis dan memenuhi syarat memilihnya secara implisit, atau saat agentRuntime.id: "codex" penyedia/model memilihnya secara eksplisit. Autentikasinya tetap berbasis akun. OpenClaw memilih autentikasi dalam urutan berikut:

1. Profil autentikasi OpenAI yang diurutkan untuk agen, sebaiknya di bawah auth.order.openai. Jalankan openclaw doctor --fix untuk memigrasikan ID profil autentikasi Codex legasi dan urutan autentikasi yang lebih lama.
2. Akun app-server yang sudah ada, seperti proses masuk ChatGPT Codex CLI lokal. Untuk home agen terisolasi bawaan, OpenClaw menjembatani akun CLI native tersebut ke app-server melalui RPC masuknya; OpenClaw tidak berbagi konfigurasi, plugin, atau penyimpanan utas CLI.
3. Hanya untuk peluncuran app-server stdio lokal, dan hanya saat app-server melaporkan tidak ada akun: CODEX_API_KEY, lalu OPENAI_API_KEY.

Proses 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 berlaku untuk jalur tanpa akun stdio lokal; kunci tersebut tidak pernah dikirim melalui koneksi app-server WebSocket. Saat profil Codex bergaya langganan dipilih, OpenClaw juga mencegah CODEX_API_KEY dan OPENAI_API_KEY masuk ke proses anak app-server stdio yang dibuat dan sebagai gantinya mengirim kredensial yang dipilih melalui RPC masuk app-server.

Saat profil langganan tersebut diblokir oleh batas penggunaan Codex, OpenClaw menandai profil sebagai diblokir hingga waktu pengaturan ulang yang diumumkan Codex dan memungkinkan pengurutan autentikasi beralih ke profil openai:* berikutnya, tanpa mengubah model yang dipilih atau keluar dari harness Codex. Setelah waktu pengaturan ulang berlalu, profil langganan kembali memenuhi syarat.

Pembuatan gambar

Plugin openai bawaan mendaftarkan pembuatan gambar melalui alat image_generate. Plugin ini mendukung pembuatan gambar berbasis kunci API OpenAI dan OAuth Codex melalui referensi model openai/gpt-image-2 yang sama.

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

gpt-image-2 adalah bawaan untuk pembuatan gambar dari teks dan pengeditan gambar OpenAI. gpt-image-1.5, gpt-image-1, dan gpt-image-1-mini tetap dapat digunakan sebagai penggantian model eksplisit. Gunakan openai/gpt-image-1.5 untuk keluaran PNG/WebP berlatar belakang transparan; API gpt-image-2 saat ini menolak background: "transparent".

Untuk permintaan berlatar belakang transparan, panggil image_generate dengan model: "openai/gpt-image-1.5", outputFormat: "png" atau "webp", dan background: "transparent"; opsi penyedia openai.background yang lebih lama masih diterima. OpenClaw juga melindungi rute publik OpenAI dan OAuth OpenAI Codex dengan menulis ulang permintaan transparan openai/gpt-image-2 bawaan menjadi gpt-image-1.5; Azure dan endpoint kustom yang kompatibel dengan OpenAI mempertahankan nama deployment/model yang dikonfigurasi.

Pengaturan yang sama tersedia untuk proses CLI headless:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "Stiker lingkaran merah sederhana pada latar belakang transparan" \  --json

Gunakan flag --output-format dan --background yang sama dengan openclaw infer image edit saat memulai dari file masukan. --openai-background tetap tersedia sebagai alias khusus OpenAI. Gunakan --quality low|medium|high|auto untuk mengontrol kualitas dan biaya OpenAI Images. Gunakan --openai-moderation low|auto untuk meneruskan petunjuk moderasi OpenAI dari image generate atau image edit.

Untuk instalasi OAuth ChatGPT/Codex, pertahankan referensi openai/gpt-image-2 yang sama. Saat profil OAuth openai dikonfigurasi, OpenClaw menyelesaikan token akses OAuth yang tersimpan tersebut dan mengirim permintaan gambar melalui backend Codex Responses; OpenClaw tidak mencoba OPENAI_API_KEY terlebih dahulu atau diam-diam melakukan fallback ke kunci API. Konfigurasikan models.providers.openai secara eksplisit dengan kunci API, URL dasar kustom, atau endpoint Azure jika Anda menginginkan rute API OpenAI Images langsung. Jika endpoint gambar kustom tersebut berada di alamat LAN/pribadi tepercaya, tetapkan juga browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw tetap memblokir endpoint gambar internal/pribadi yang kompatibel dengan OpenAI kecuali pilihan ikut serta ini tersedia.

Buat:

/tool image_generate model=openai/gpt-image-2 prompt="Poster peluncuran OpenClaw yang rapi di macOS" size=3840x2160 count=1

Buat PNG transparan:

/tool image_generate model=openai/gpt-image-1.5 prompt="Stiker lingkaran merah sederhana pada latar belakang transparan" outputFormat=png background=transparent

Edit:

/tool image_generate model=openai/gpt-image-2 prompt="Pertahankan bentuk objek, ubah bahannya menjadi kaca tembus cahaya" image=/path/to/reference.png size=1024x1536

Pembuatan video

Plugin openai bawaan mendaftarkan pembuatan video melalui alat video_generate.

Permintaan image-to-video OpenAI menggunakan POST /v1/videos dengan sebuah gambar input_reference. Pengeditan video tunggal menggunakan POST /v1/videos/edits dengan video yang diunggah di bidang video.

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

Kontribusi prompt GPT-5

OpenClaw menambahkan kontribusi prompt GPT-5 bersama untuk model keluarga GPT-5 pada penyedia openai (termasuk referensi Codex lama sebelum perbaikan yang dinormalisasi menjadi openai/*). Penyedia lain yang juga melayani ID model keluarga GPT-5, seperti rute OpenRouter atau opencode, tidak menerima overlay ini; penerapannya dibatasi berdasarkan ID penyedia openai, bukan hanya berdasarkan ID model. Model GPT-4.x yang lebih lama tidak pernah menerimanya.

Harness app-server Codex native tidak menerima kontrak perilaku persona/disiplin- alat atau overlay gaya interaksi ramah melalui instruksi pengembang; Codex native mempertahankan perilaku dasar, model, dan dokumen proyek milik Codex, serta OpenClaw menonaktifkan kepribadian bawaan Codex untuk utas native agar berkas kepribadian ruang kerja agen tetap menjadi acuan. OpenClaw hanya menyumbangkan konteks runtime ke utas Codex native: pengiriman kanal, alat dinamis OpenClaw, delegasi ACP, konteks ruang kerja, dan Skills OpenClaw. Teks panduan Heartbeat dari kontribusi yang sama ini merupakan satu-satunya pengecualian: giliran Heartbeat Codex native memang menerimanya, yang disuntikkan sebagai instruksi kolaborasi khusus, bukan melalui hook kontribusi prompt bersama.

Kontribusi GPT-5 menambahkan kontrak perilaku bertag untuk persistensi persona, keamanan eksekusi, disiplin alat, bentuk keluaran, pemeriksaan penyelesaian, dan verifikasi pada prompt rakitan OpenClaw yang cocok. Perilaku balasan khusus kanal dan pesan senyap tetap berada dalam prompt sistem OpenClaw bersama dan kebijakan pengiriman keluar. Lapisan gaya interaksi ramah bersifat terpisah dan dapat dikonfigurasi.

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

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

Suara dan ucapan

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

Endpoint Azure OpenAI

Penyedia openai yang dibundel dapat menargetkan sumber daya Azure OpenAI untuk pembuatan gambar dengan mengganti URL dasar. Pada jalur pembuatan gambar, OpenClaw mendeteksi nama host Azure pada models.providers.openai.baseUrl dan beralih ke format permintaan Azure secara otomatis.

Gunakan Azure OpenAI ketika:

• Anda sudah memiliki langganan, kuota, atau perjanjian perusahaan Azure OpenAI
• Anda memerlukan residensi data regional atau kontrol kepatuhan yang disediakan Azure
• Anda ingin mempertahankan lalu lintas di dalam tenancy Azure yang sudah ada

Konfigurasi

Untuk pembuatan gambar Azure melalui penyedia openai yang dibundel, arahkan models.providers.openai.baseUrl ke sumber daya Azure Anda dan atur 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 berikut untuk rute pembuatan gambar Azure:

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

Untuk permintaan 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 permintaan
• Menggunakan batas waktu permintaan default 600 detik untuk panggilan pembuatan gambar Azure. Nilai timeoutMs per panggilan tetap menggantikan nilai default ini.

URL dasar lainnya (OpenAI publik, proksi yang kompatibel dengan OpenAI) tetap menggunakan format permintaan gambar OpenAI standar.

Versi API

Atur AZURE_OPENAI_API_VERSION untuk menetapkan versi pratinjau atau GA Azure tertentu bagi jalur pembuatan gambar Azure:

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

Nilai defaultnya adalah 2024-12-01-preview ketika variabel tidak diatur.

Nama model adalah nama deployment

Azure OpenAI mengikat model ke deployment. Untuk permintaan pembuatan gambar Azure yang dirutekan melalui penyedia openai yang dibundel, bidang 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="Poster yang bersih" size=1024x1024 count=1

Aturan nama deployment yang sama berlaku untuk setiap panggilan pembuatan gambar yang dirutekan melalui penyedia openai yang dibundel.

Ketersediaan regional

Pembuatan gambar Azure saat ini hanya tersedia di sebagian wilayah (misalnya eastus2, swedencentral, polandcentral, westus3, uaenorth). Periksa daftar wilayah Microsoft terkini sebelum membuat deployment, dan pastikan model tertentu tersebut ditawarkan di wilayah Anda.

Perbedaan parameter

Azure OpenAI dan OpenAI publik tidak selalu menerima parameter gambar yang sama. Azure mungkin menolak opsi yang diizinkan OpenAI publik (misalnya nilai background tertentu pada gpt-image-2) atau hanya menyediakannya 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.

Konfigurasi lanjutan

Contoh params per model di bawah membentuk permintaan penyedia tersemat OpenClaw. Mengonfigurasinya merupakan perilaku permintaan yang ditentukan, sehingga rute auto yang seharusnya memenuhi syarat tetap berada di OpenClaw, alih-alih memilih Codex secara implisit. Harness app-server Codex native mengelola transport dan pengaturan permintaannya sendiri; agentRuntime.id: "codex" eksplisit gagal secara tertutup jika rute efektif tidak dinyatakan kompatibel dengan Codex.

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

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  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: {      embeddedAgent: { executionContract: "default" },    },  },}

Terkait