Sebuah pengaturan OpenCode OpenAI compatible provider berguna ketika Anda ingin OpenCode berbicara ke rute model yang berperilaku seperti OpenAI Chat Completions API, sementara tim Anda tetap menjaga kepemilikan kunci, routing model, dan peninjauan penggunaan dalam satu gateway.
Bagian pentingnya adalah OpenCode memiliki jalur custom-provider yang terdokumentasi. Dalam dokumen provider OpenCode yang diperiksa pada 8 Juli 2026, alurnya adalah: tambahkan kredensial dengan /connect, pilih Other untuk provider yang belum terdaftar, berikan ID yang mudah diingat untuk provider tersebut, konfigurasi provider di opencode.json, lalu jalankan /models untuk memilih dari model yang telah dikonfigurasi.
Flatkey cocok dengan pola itu sebagai gateway di belakang provider. Anda tetap menggunakan OpenCode sebagai coding agent, arahkan provider ke base URL API Flatkey yang kompatibel dengan OpenAI, dan verifikasi bahwa traffic model OpenCode muncul di usage atau log permintaan Flatkey sebelum menjadikannya rute default.
Jawaban singkat untuk pengaturan OpenCode OpenAI compatible provider
Gunakan bentuk pengaturan ini saat endpoint model kompatibel dengan Chat Completions.
| Keputusan | Nilai yang direkomendasikan | Mengapa ini penting |
|---|---|---|
| Provider ID | flatkey |
ID harus cocok antara /connect, opencode.json, dan model yang dipilih. |
| Paket NPM | @ai-sdk/openai-compatible |
Dokumen OpenCode menyebutkan paket ini untuk provider kompatibel OpenAI yang menggunakan /v1/chat/completions. |
| OpenCode API base URL | https://router.flatkey.ai/v1 |
Situs publik Flatkey mengarahkan klien yang kompatibel dengan OpenAI ke root API ini. |
| ID model | Alias model Flatkey terkini yang tersedia untuk key Anda | OpenCode menggunakan ID model yang dikonfigurasi di pemilih /models. |
| Verifikasi | Respons OpenCode plus log request atau usage Flatkey | Ini membuktikan bahwa request coding-agent menggunakan rute gateway yang dimaksud. |
| Rollback | Pertahankan nilai model sebelumnya dan konfigurasi provider sebelumnya |
Perubahan provider harus bisa dibalik tanpa refactoring prompt atau alur kerja agent Anda. |
Panduan OpenCode OpenAI compatible provider ini menggunakan template. Validasi alias model dan family endpoint yang tepat terhadap akun Flatkey Anda sebelum merutekan pekerjaan coding-agent produksi.
Apa yang dibutuhkan OpenCode
OpenCode memiliki dua bagian state yang terpisah untuk custom provider.
| Lapisan OpenCode | Yang Anda konfigurasi | Perilaku sumber yang harus dipatuhi |
|---|---|---|
| Kredensial | API key dimasukkan melalui /connect di bawah Other |
Provider ID yang Anda masukkan di sini harus cocok dengan provider ID di config. |
| Konfigurasi provider | provider.<id> di opencode.json |
Config menamai paket AI SDK, base URL, model, dan header opsional atau referensi API key. |
| Pemilihan model | pemilih /models atau nilai model default |
Model provider yang dikonfigurasi akan muncul setelah provider dikonfigurasi. |
| Default runtime | model dan small_model opsional |
Config OpenCode mendukung default provider/model untuk tugas normal dan ringan. |
Config OpenCode bisa berupa JSON atau JSONC. Anda dapat menempatkannya secara global di ~/.config/opencode/opencode.json, atau di root proyek sebagai opencode.json. Config proyek memiliki prioritas standar yang lebih tinggi, jadi gunakan file proyek saat Anda ingin satu repository menguji Flatkey tanpa mengubah setiap workspace OpenCode.
Langkah 1: Buat key Flatkey untuk OpenCode
Buat key Flatkey untuk workload ini dan catat tiga nilai di luar source control.
FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias
Pisahkan root API dari path endpoint. Config provider OpenCode harus menggunakan https://router.flatkey.ai/v1 sebagai options.baseURL; smoke test HTTP langsung menambahkan /chat/completions.
Sebelum menghubungkan OpenCode, jalankan tes langsung terhadap key Flatkey dan alias model yang sama.
curl "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{ "role": "user", "content": "Reply with exactly: flatkey route ok" }
]
}'
Jika request langsung ini gagal, perbaiki key Flatkey, alias model, family endpoint, atau route akun sebelum men-debug OpenCode. Sebuah OpenCode OpenAI compatible provider tidak dapat mengompensasi alias model yang tidak dapat dipanggil oleh akun gateway.
Langkah 2: Tambahkan kredensial Flatkey di OpenCode
OpenCode menyimpan kredensial provider melalui /connect. Di TUI OpenCode:
/connect
Pilih Other, masukkan provider ID seperti flatkey, lalu tempelkan API key Flatkey. Jangan tempelkan base URL di prompt kredensial. Key membuktikan identitas; base URL berada di opencode.json.
Gunakan provider ID yang membosankan. flatkey lebih baik daripada flatkey-prod-openai-compatible-gateway-v2 karena Anda akan mengetiknya di ID model dan catatan rollback.
Langkah 3: Tambahkan konfigurasi provider OpenCode
Buat atau perbarui opencode.json di root project yang ingin Anda uji.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"flatkey": {
"npm": "@ai-sdk/openai-compatible",
"name": "Flatkey",
"options": {
"baseURL": "https://router.flatkey.ai/v1"
},
"models": {
"your-current-flatkey-model-alias": {
"name": "Flatkey primary model"
}
}
}
},
"model": "flatkey/your-current-flatkey-model-alias"
}
Ini adalah konfigurasi OpenCode OpenAI compatible provider yang paling minimal. Ini memberi OpenCode provider bernama flatkey, memberi tahu OpenCode untuk menggunakan paket AI SDK yang kompatibel dengan OpenAI, dan menampilkan satu alias model di pemilih model.
Jika Anda ingin OpenCode menggunakan rute yang lebih kecil untuk pekerjaan ringan, tambahkan small_model hanya setelah rute utama berfungsi.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"flatkey": {
"npm": "@ai-sdk/openai-compatible",
"name": "Flatkey",
"options": {
"baseURL": "https://router.flatkey.ai/v1"
},
"models": {
"primary-flatkey-model-alias": {
"name": "Flatkey primary"
},
"lighter-flatkey-model-alias": {
"name": "Flatkey lightweight"
}
}
}
},
"model": "flatkey/primary-flatkey-model-alias",
"small_model": "flatkey/lighter-flatkey-model-alias"
}
Gunakan alias model yang benar-benar dapat dipanggil oleh kunci Flatkey Anda. Jika akun Anda mengekspos rute terautentikasi /v1/models, bandingkan ID model yang dikonfigurasi dengan respons tersebut. Jika tidak, salin alias dari dashboard Flatkey atau direktori model saat ini dan verifikasi dengan permintaan nyata.
Langkah 4: Pilih dan uji model di OpenCode
Setelah menyimpan konfigurasi, buka pemilih model.
/models
Pilih model provider Flatkey. Lalu jalankan prompt kecil di OpenCode:
Reply with exactly: opencode flatkey route ok
Jangan langsung memindahkan seluruh alur kerja coding. Pertama, simpan paket verifikasi yang ringkas.
| Pemeriksaan | Syarat lolos | Bukti yang disimpan |
|---|---|---|
| Provider muncul | /models menampilkan model Flatkey yang dikonfigurasi |
Screenshot atau catatan terminal dengan ID model yang dipilih. |
| Autentikasi berfungsi | OpenCode menerima respons model normal, bukan 401 atau 403 |
Pemilik kunci yang disamarkan, waktu respons, dan timestamp permintaan. |
| Base URL bersih | Tidak ada /v1/v1 ganda, tidak ada perilaku /chat/completions yang hilang |
options.baseURL akhir dan endpoint curl langsung. |
| Flatkey melihatnya | Permintaan muncul di penggunaan Flatkey atau log permintaan | Timestamp permintaan, alias model, field token atau unit, label kunci/workload. |
| Rollback tersedia | Anda bisa kembali ke provider/model sebelumnya dalam satu edit konfigurasi | model sebelumnya, ID provider sebelumnya, dan pemilik kunci sebelumnya. |
Ini mengubah migrasi OpenCode OpenAI compatible provider menjadi perubahan operasional kecil, bukan penggantian provider secara buta.
Langkah 5: Pisahkan Chat Completions dan Responses
Dokumentasi custom-provider OpenCode menyoroti batas paket: gunakan @ai-sdk/openai-compatible untuk provider yang kompatibel dengan OpenAI dan memakai /v1/chat/completions; jika provider atau model memakai /v1/responses, gunakan @ai-sdk/openai.
Artinya, rute Flatkey pertama sebaiknya merupakan model bergaya Chat Completions kecuali Anda memiliki bukti terbaru bahwa model dan jalur klien yang Anda pilih menggunakan keluarga endpoint yang berbeda.
Gunakan tabel keputusan ini sebelum menambahkan lebih banyak model.
| Rute model | Arah paket OpenCode | Yang diuji |
|---|---|---|
| Kompatibel Chat Completions | @ai-sdk/openai-compatible |
Chat biasa, streaming, perilaku panggilan tool jika diperlukan. |
| Rute bergaya Responses | @ai-sdk/openai menurut dokumentasi OpenCode |
Pembuatan response, penanganan tool, dan parsing output. |
| Rute campuran di bawah satu provider | Override paket per model jika konfigurasi Anda menggunakannya | Satu model pada satu waktu, dengan log terpisah. |
Untuk sebagian besar pekerjaan penyiapan, mulailah dengan satu rute Chat Completions. Tambahkan streaming, panggilan tool, dan alias model sekunder setelah smoke test OpenCode OpenAI compatible provider pertama terlihat di Flatkey.
Langkah 6: Tambahkan kontrol tim setelah rutenya berfungsi
Setelah OpenCode dapat memanggil Flatkey, buat rute tersebut dapat diamati.
| Kontrol | Mengapa ini membantu |
|---|---|
| Penamaan kunci | Berikan label pada kunci untuk OpenCode, lingkungan, tim, atau repositori. |
| Persetujuan model | Batasi konfigurasi pertama pada alias yang disetujui sebelum menambahkan pilihan model yang lebih luas. |
| Peninjauan penggunaan | Periksa log permintaan atau penggunaan Flatkey berdasarkan timestamp setelah setiap pengujian OpenCode. |
| Peninjauan biaya | Cocokkan penggunaan model, token, dan kunci dengan pemilik anggaran. |
| Kebijakan timeout | Gunakan opsi provider OpenCode hanya setelah Anda mengetahui route dasar berfungsi. |
| Catatan rollback | Simpan nilai provider dan model sebelumnya sebelum menjadikan Flatkey sebagai default. |
Di sinilah Flatkey menjadi lebih dari sekadar base URL. Sebuah provider OpenCode OpenAI compatible yang berfungsi juga harus memberi tim platform, finance, dan operations tempat untuk meninjau penggunaan model dan mengubah route tanpa meminta setiap developer mengelola akun provider terpisah.
Untuk perencanaan migrasi yang lebih luas, pasangkan panduan ini dengan panduan migrasi API OpenAI-compatible Flatkey. Jika Anda membandingkan alat coding yang berdekatan, lihat panduan provider OpenAI-compatible Continue.dev dan panduan setup OpenAI-compatible Roo Code.
Memecahkan masalah provider OpenCode OpenAI compatible
| Gejala | Penyebab yang mungkin | Yang perlu diperiksa |
|---|---|---|
Provider tidak muncul di /models |
Mismatch ID provider atau konfigurasi tidak dimuat | Pastikan ID /connect dan key provider sama-sama flatkey; pastikan file config berada di root proyek atau path config global yang Anda harapkan. |
401 atau 403 |
Kunci Flatkey hilang, dicabut, atau salah | Masukkan ulang kredensial dengan /connect; jangan pernah mencetak kunci lengkap di log. |
404 |
API root atau family endpoint salah | options.baseURL harus berupa API root, bukan URL lengkap /chat/completions. |
| Model tidak ditemukan | Alias tidak tersedia untuk kunci atau family endpoint | Verifikasi alias model di Flatkey dan uji satu permintaan langsung. |
| Streaming macet | Masalah kemampuan route, dukungan model, atau chunk timeout | Buktikan chat non-streaming terlebih dahulu, lalu sesuaikan chunkTimeout OpenCode hanya jika diperlukan. |
| Penggunaan tidak muncul di Flatkey | Permintaan tidak melalui Flatkey atau log difilter | Cari berdasarkan timestamp, label kunci, alias model, dan lingkungan. |
| Fitur responses gagal | Paket yang salah untuk family endpoint | Periksa kembali apakah route yang dipilih menggunakan /v1/chat/completions atau /v1/responses. |
Jika permintaan pertama gagal, jangan ubah prompt, agent, izin, atau kode repositori dulu. Jaga surface debugging provider OpenCode OpenAI compatible tetap kecil: kredensial, ID provider, base URL, package, alias model, dan satu permintaan chat biasa.
Daftar periksa akhir
Sebelum menggunakan Flatkey sebagai route default OpenCode, pastikan:
/connectmemiliki kredensial Flatkey di bawah ID provider yang sama yang digunakan diopencode.json.provider.flatkey.npmadalah@ai-sdk/openai-compatibleuntuk route Chat Completions.provider.flatkey.options.baseURLadalahhttps://router.flatkey.ai/v1.modelmengarah ke nilaiflatkey/<model-alias>yang sudah dikonfigurasi./modelsmenampilkan model Flatkey yang dikonfigurasi.- Prompt OpenCode satu baris berhasil dijalankan.
- Log penggunaan atau permintaan Flatkey menampilkan permintaan uji OpenCode.
- Route provider/model sebelumnya didokumentasikan untuk rollback.
Setup provider OpenCode OpenAI compatible selesai ketika provider dikonfigurasi, dapat dipilih, diverifikasi di log Flatkey, dan dapat dikembalikan. Saat Anda siap merutekan traffic model coding-agent melalui satu kunci, dapatkan kunci Flatkey dan mulai dengan satu prompt OpenCode berisiko rendah.
