Self-host gateway AI Magpie: ganti model dengan bebas di Claude Code, Codex, dan agen lainnya

Secara bawaan, Claude Code memanggil model Anthropic dan Codex memanggil model OpenAI. Untuk mencoba DeepSeek di Claude Code, atau pindah ke penyedia lain saat kuota satu penyedia habis, Anda harus mengubah alamat dan kunci di file konfigurasi setiap alat.

Magpie adalah gateway AI open source (MIT) yang dibuat untuk ini. Anda menghubungkan penyedia ke Magpie, dan agen Anda cukup mengenal alamat Magpie. Magpie mendukung format OpenAI Chat, OpenAI Responses, Anthropic Messages, dan Gemini, serta menerjemahkan di antara format-format itu, sehingga Claude Code bisa memakai model selain milik Anthropic. Magpie juga menyediakan:

• Failover dan grup routing: saat sebuah model error atau kuotanya habis, Magpie beralih ke model cadangan atau akun lain, dan agen tidak melihat error tersebut.
• Pemakaian dan biaya: token, rasio cache hit, dan perkiraan biaya, per model dan per klien.
• Kunci gateway: kunci tersendiri untuk setiap klien, dengan batas dan daftar model masing-masing.

Magpie biasanya dijalankan di komputer Anda sendiri. Artikel ini memakai template Magpie di Zenavo untuk menjalankannya di server, sehingga laptop, desktop, dan komputer rekan tim Anda memakai satu pengaturan yang sama. Jika yang Anda butuhkan adalah kunci API dan kuota untuk seluruh tim, lihat juga New API: New API untuk mengelola kunci API tim di satu tempat, Magpie agar setiap agen bisa memilih model apa pun.

Server, Zenavo, dan API model ditagih terpisah. Magpie meneruskan dan menghitung permintaan; Magpie tidak membuat panggilan model lebih murah.

Deploy Magpie

Pertama, hubungkan server Linux ke Zenavo, lalu buka template Magpie, pilih server, dan deploy.

Pengaturan template saat ini:

Pengaturan	Nilai atau fungsi
Image	ghcr.io/yetone/magpie:latest
Perintah	web --addr 0.0.0.0:3430 --no-open, yang menjalankan antarmuka web
Port HTTP	3430, untuk antarmuka web sekaligus API yang dipanggil agen Anda
Volume	/config, berisi penyedia, kunci gateway, data login, dan pemakaian
MAGPIE_WEB_KEY	Dibuat otomatis saat proyek dibuat; kunci untuk masuk ke antarmuka web
Memori	Disarankan 512 MB

latest mengikuti upstream. Sebelum mengandalkannya, ubah tag di Source pada Settings layanan ke versi yang sudah Anda uji, atau ke stable, kanal mingguan Magpie.

Tambahkan domain dan masuk

Di tab Networking layanan magpie, tambahkan domain untuk port 3430, misalnya magpie.example.com. Tambahkan record DNS A yang mengarah ke server Anda dan tunggu HTTPS aktif. Langkah-langkahnya ada di Domain.

Lalu salin nilai MAGPIE_WEB_KEY dari tab Variable layanan, buka https://magpie.example.com, dan tempel kunci itu di tempat yang diminta halaman. Browser akan tetap dalam keadaan masuk.

Kunci ini adalah kata sandi admin Magpie. Siapa pun yang memilikinya bisa mengubah semua pengaturan dan melihat kunci penyedia yang Anda tambahkan. Karena itu:

• Jangan berikan kepada orang yang hanya perlu memanggil model. Mereka membutuhkan kunci gateway, yang dijelaskan di bawah.
• Jangan sertakan dalam tangkapan layar, obrolan, atau repositori.
• Jika Anda menduga kunci ini bocor, ganti di Variable dengan nilai acak baru (minimal 16 karakter: huruf, angka, atau - . _ ~), simpan, lalu restart layanan.

Dokumentasi Magpie menyarankan agar antarmuka web tetap berada di komputer Anda sendiri atau di dalam VPN. Di domain publik, hanya kunci ini yang melindunginya, jadi jaga baik-baik seperti di atas.

Atur alamat publik

Di Variable, tambahkan MAGPIE_PUBLIC_URL dengan nilai https://magpie.example.com, simpan, lalu restart. Magpie berjalan di dalam container dan hanya melihat alamat internal container; dengan variabel ini, alamat dan contoh pengaturan yang ditampilkannya memakai domain Anda.

Tambahkan penyedia

Tambahkan penyedia di halaman Providers pada antarmuka web. Magpie punya preset untuk Anthropic, OpenAI, Google Gemini, DeepSeek, Kimi, Zhipu GLM, Qwen, Mistral, xAI, OpenRouter, dan lainnya, serta menerima URL apa pun yang kompatibel dengan OpenAI atau Anthropic. Masukkan kunci API penyedia, simpan, lalu pastikan modelnya muncul di daftar.

Nama model di Magpie berbentuk penyedia/model, misalnya deepseek/deepseek-v4-pro. Anda juga bisa membuat grup routing: sekumpulan model yang menerima permintaan secara berurutan, bergiliran, atau berdasarkan pemakaian, lalu pindah ke model berikutnya saat satu gagal. Agen memakai nama grup sebagai nama model.

Magpie juga bisa memakai langganan seperti Claude atau ChatGPT sebagai penyedia. Masuk ke langganan itu dari server butuh langkah tambahan, yang dijelaskan di dokumentasi Docker Magpie. Baca dulu ketentuan setiap penyedia: langganan pribadi biasanya hanya untuk Anda sendiri, jadi jangan bagikan kepada orang lain lewat gateway.

Bagikan kunci gateway

Magpie di server hanya menerima permintaan yang membawa kunci gateway aktif; permintaan lain mendapat 401. Di antarmuka web, buka Gateway → Gateway keys, buat kunci untuk setiap komputer atau orang, lalu salin. Kunci lengkap hanya ditampilkan saat dibuat.

Setiap kunci bisa punya pengaturannya sendiri:

• Batas: token dan perkiraan biaya per hari, minggu, bulan, atau total;
• Model: misalnya hanya deepseek/*;
• Status: jika kunci bocor, nonaktifkan atau rotasi tanpa memengaruhi klien lain dan tanpa merotasi kunci penyedia Anda.

Pemegang kunci gateway bisa membuka https://magpie.example.com/me, memasukkan kuncinya, dan melihat batas, pemakaian, model, serta pengaturan siap salin untuk Claude Code dan Codex miliknya sendiri. Mereka tidak bisa melihat kunci lain atau penyedia.

Hubungkan Claude Code

Di komputer Anda, atur:

export ANTHROPIC_BASE_URL="https://magpie.example.com"
export ANTHROPIC_AUTH_TOKEN="kunci gateway Magpie Anda"
export ANTHROPIC_MODEL="deepseek/deepseek-v4-pro"
claude

ANTHROPIC_BASE_URL cukup berisi domain, tanpa /v1; Claude Code menambahkan /v1/messages sendiri. Isi ANTHROPIC_MODEL dengan model atau grup routing yang Anda lihat di Magpie, atau ganti dengan /model di dalam Claude Code. Jika Anda juga ingin memeriksa log, men-deploy, dan melakukan rollback layanan Zenavo langsung dari Claude Code dengan MCP dan Skills, lihat Deploy dan debug proyek Zenavo dari Claude Code.

Hubungkan Codex CLI

Codex CLI mendefinisikan provider kustom di ~/.codex/config.toml:

model = "deepseek/deepseek-v4-pro"
model_provider = "magpie"

[model_providers.magpie]
name = "magpie"
base_url = "https://magpie.example.com/v1"
model_catalog_url = "https://magpie.example.com/v1/codex/models"
env_key = "MAGPIE_API_KEY"
wire_api = "responses"
supports_websockets = false

Lalu jalankan export MAGPIE_API_KEY="kunci gateway Anda" dan mulai codex. Di sini base_url memakai /v1, berbeda dengan Claude Code. model_catalog_url membuat Codex membaca dari Magpie daftar model yang boleh dipakai kunci ini.

Untuk antarmuka web atau klien lain yang kompatibel dengan OpenAI (seperti Open WebUI atau LobeHub self-hosted), pakai https://magpie.example.com/v1 sebagai base URL dan kunci gateway sebagai kunci API.

Cadangan dan pembaruan

Volume /config berisi kunci API penyedia, data login langganan, dan kunci gateway, jadi lindungi cadangannya seperti Anda melindungi kunci itu sendiri.

Pada jadwal pemeliharaan, hentikan proyek, cadangkan volume dari tab Backup & Restore layanan magpie, jalankan kembali proyek, lalu unduh satu salinan untuk disimpan. Sebelum memperbarui, baca catatan rilis Magpie, lalu buat cadangan sebelum mengganti versi image.

FAQ

Agen saya mendapat 401. Permintaan tidak membawa kunci gateway, atau kuncinya nonaktif. Magpie di server tidak menerima kunci pengganti magpie yang diterima instalasi lokal. Pastikan juga Anda memakai kunci gateway, bukan MAGPIE_WEB_KEY.

Claude Code mengembalikan 404 atau tidak bisa terhubung. Periksa apakah ANTHROPIC_BASE_URL diakhiri /v1 yang berlebih.

Model tidak ditemukan atau ditolak (403). Pakai bentuk penyedia/model, dan pastikan model itu termasuk yang boleh dipakai kunci gateway ini. Minta https://magpie.example.com/v1/models dengan kunci tersebut untuk melihat semua model yang boleh dipakainya.

Siapa yang melihat kode saya? Permintaan tetap dikirim ke penyedia yang Anda pilih; menjalankan gateway di server sendiri tidak membuat data tetap berada di sana. Magpie punya fitur penyamaran privasi opsional yang mengganti kunci, kata sandi, dan alamat email dengan placeholder sebelum permintaan dikirim; aktifkan di Settings → Privacy. Magpie mengirim statistik anonim sekali sehari (tanpa prompt, kunci, atau pemakaian), yang bisa dimatikan di halaman yang sama atau dengan DO_NOT_TRACK=1 di Variable.

Apakah server kecil sudah cukup? Magpie sendiri ringan; template menyarankan memori 512 MB. Beban datang dari permintaan streaming yang berjalan bersamaan, jadi pantau memori dan bandwidth saat beberapa orang memakainya sekaligus.

Mulai dari template Magpie: tambahkan domain dan simpan kunci masuk dengan aman, tambahkan penyedia, bagikan kunci gateway, lalu arahkan Claude Code dan Codex ke sana.