OpenAI

OpenAI menyediakan API pengembang untuk model GPT, dan Codex juga tersedia sebagai agen coding paket ChatGPT melalui klien Codex OpenAI. OpenClaw menggunakan satu id penyedia, openai, untuk kedua bentuk autentikasi.

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, embedding, ucapan, 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 - referensi model Codex lama diperbaiki oleh openclaw doctor --fix menjadi openai/* plus runtime Codex.

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

Penyedia, model, runtime, dan kanal adalah lapisan terpisah. Jika label tersebut mulai tercampur, baca Runtime agen sebelum mengubah konfigurasi.

Pilihan cepat

Peta penamaan

Nama-namanya mirip tetapi tidak dapat saling dipertukarkan:

Ini berarti konfigurasi dapat dengan sengaja berisi referensi model openai/* sementara profil autentikasi menunjuk ke kredensial kunci API atau OAuth ChatGPT/Codex. Gunakan auth.order.openai untuk konfigurasi; openclaw doctor --fix menulis ulang referensi model Codex lama, id profil autentikasi Codex lama, dan urutan autentikasi Codex lama ke rute OpenAI kanonis.

Pratinjau terbatas GPT-5.6

OpenClaw mengenali tiga id model GPT-5.6 publik:

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

Ketiganya mengekspos penalaran max dalam katalog server aplikasi Codex saat ini. Pengumuman peluncuran OpenAI menggambarkan 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 pratinjau.

Akses masuk daftar izin selama pratinjau dan dapat diberikan secara terpisah untuk API dan Codex. Paket ChatGPT berbayar saja tidak memberikan akses. OpenClaw mempertahankan openai/gpt-5.5 sebagai default; memilih referensi GPT-5.6 tanpa akses mengembalikan galat akses upstream alih-alih fallback 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 kompatibel OpenAI yang memerlukan label embedding asimetris, setel queryInputType dan documentInputType di bawah memorySearch. OpenClaw meneruskan keduanya sebagai field 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

Pilih metode autentikasi yang Anda inginkan dan ikuti langkah penyiapan.

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.5" } } },}

{  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.5

openclaw models list --provider openai

{  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: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 ref model openai/* ditambah konfigurasi runtime yang dihilangkan atau agentRuntime.id: "codex" provider/model, 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. Jalankan openclaw doctor --fix untuk memigrasikan id profil auth Codex lama yang usang dan urutan auth Codex lama.
2. Akun app-server yang sudah ada, seperti login ChatGPT CLI Codex lokal.
3. Hanya untuk peluncuran app-server stdio lokal, CODEX_API_KEY, lalu OPENAI_API_KEY, ketika app-server melaporkan tidak ada akun dan masih memerlukan auth OpenAI.

Itu berarti login 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 stdio lokal tanpa akun; itu tidak dikirim ke koneksi app-server WebSocket. Ketika profil Codex bergaya langganan dipilih, OpenClaw juga menjauhkan CODEX_API_KEY dan OPENAI_API_KEY dari child app-server stdio yang dijalankan dan mengirim kredensial terpilih melalui RPC login app-server. Ketika profil langganan tersebut diblokir oleh batas penggunaan Codex, OpenClaw dapat berotasi ke profil kunci API openai:* berurutan berikutnya tanpa mengubah model yang dipilih atau keluar dari harness Codex. Setelah waktu reset langganan lewat, profil langganan tersebut memenuhi syarat lagi.

Pembuatan gambar

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

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

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 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, agen harus memanggil 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 OpenAI Codex OAuth dengan menulis ulang permintaan transparan default openai/gpt-image-2 menjadi gpt-image-1.5; Azure dan endpoint kustom yang kompatibel dengan OpenAI tetap menggunakan 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. Gunakan --quality low|medium|high|auto saat Anda perlu mengontrol kualitas dan biaya OpenAI Images. Gunakan --openai-moderation low|auto untuk meneruskan petunjuk moderasi khusus penyedia OpenAI dari image generate atau image edit.

Untuk instalasi ChatGPT/Codex OAuth, pertahankan ref openai/gpt-image-2 yang sama. Saat profil OAuth openai dikonfigurasi, OpenClaw menyelesaikan token akses OAuth tersimpan tersebut dan mengirim permintaan gambar melalui backend Codex Responses. OpenClaw tidak lebih dulu mencoba OPENAI_API_KEY atau diam-diam kembali 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 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 privat/internal yang kompatibel dengan OpenAI 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 bawaan openai mendaftarkan pembuatan video melalui alat video_generate.

Permintaan gambar-ke-video OpenAI menggunakan POST /v1/videos dengan input_reference gambar. Edit satu video 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 eksekusi keluarga GPT-5 pada permukaan prompt yang dirakit OpenClaw. Ini berlaku berdasarkan id model, sehingga rute OpenClaw/penyedia seperti ref lama pra-perbaikan (ref GPT-5.5 Codex lama), openrouter/openai/gpt-5.5, opencode/gpt-5.5, dan ref GPT-5 kompatibel lainnya menerima overlay yang sama. Model GPT-4.x yang lebih lama tidak.

Harness Codex native bawaan tidak menerima overlay GPT-5 OpenClaw ini melalui instruksi developer app-server Codex. Codex native tetap mempertahankan perilaku dasar, model, dan dokumen proyek milik Codex, sementara OpenClaw menonaktifkan kepribadian bawaan Codex untuk thread native agar file kepribadian workspace agen tetap otoritatif. OpenClaw hanya menyumbangkan konteks runtime seperti pengiriman channel, alat dinamis OpenClaw, delegasi ACP, konteks workspace, dan Skills OpenClaw.

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 channel dan pesan senyap tetap berada di prompt sistem OpenClaw bersama dan kebijakan pengiriman keluar. Lapisan gaya interaksi ramah 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

Provider 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 permintaan Azure secara otomatis.

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 provider openai bawaan, arahkan models.providers.openai.baseUrl ke resource 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 ini 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 alih-alih Authorization: Bearer
• Menggunakan path yang dicakup deployment (/openai/deployments/{deployment}/...)
• Menambahkan ?api-version=... ke setiap permintaan
• Menggunakan timeout permintaan default 600 detik 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 permintaan gambar OpenAI standar.

Versi API

Atur AZURE_OPENAI_API_VERSION untuk menyematkan versi preview 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 diatur.

Nama model adalah nama deployment

Azure OpenAI mengikat model ke deployment. Untuk permintaan pembuatan gambar Azure yang dirutekan melalui provider openai bawaan, field model di OpenClaw harus berupa nama deployment Azure yang Anda konfigurasikan di portal Azure, bukan id model OpenAI publik.

Jika Anda membuat deployment bernama gpt-image-2-prod yang menyajikan 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 provider openai bawaan.

Ketersediaan regional

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

Perbedaan parameter

Azure OpenAI dan OpenAI publik tidak selalu menerima parameter gambar yang sama. Azure dapat menolak opsi yang diizinkan 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 error validasi, periksa set parameter yang didukung oleh deployment dan versi API spesifik Anda di portal Azure.

Konfigurasi lanjutan

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

Terkait