Tutorial langkah demi langkah: Hubungkan semua agen dengan satu kunci menggunakan API gateway terpadu magpie open-source (contoh: Claude Code, Codex, Pi, Hermes)

Catatan penulis: Ini tutorial yang bisa langsung diikuti sampai selesai. Setelah membaca dan mempraktikkannya, Anda akan punya konfigurasi “satu kunci, satu alamat gateway, dan bisa mengelola sebanyak apa pun Agent yang terpasang”. Nantinya, jika ingin mengganti model atau merotasi kunci, Anda hanya perlu mengubahnya di satu tempat.

Sebelum mulai, pahami dulu yang akan Anda lakukan

• Tujuan: Semua Agent pemrograman di komputer Anda menggunakan kunci API dan alamat upstream yang sama. Contoh dalam artikel ini mencakup Claude Code, Codex, Pi, dan Hermes. Hubungkan saja Agent yang sudah terpasang.
• Waktu: Sekitar 30 menit, tidak termasuk waktu pendaftaran dan pengunduhan.
• Prasyarat: Token APIYI (bisa juga kunci dari layanan proksi API atau layanan resmi yang kompatibel dengan OpenAI/Anthropic), komputer yang bisa menjalankan baris perintah, dan setidaknya satu Agent yang sudah terpasang.
• Tingkat kesulitan: ★★☆☆☆. Cukup bisa mengeklik beberapa kali dan menyalin-tempel. Anda tidak perlu mengetik perintah apa pun.

Peta langkah tutorial

Pahami dalam Tiga Menit: Apa yang Sebenarnya Dilakukan magpie?

Kalau Anda hanya ingin langsung mengikuti langkah-langkahnya, bagian ini boleh dilewati. Namun, meluangkan tiga menit untuk membacanya bisa sangat membantu saat Anda perlu mengatasi masalah nanti.

Setiap Agent punya kebutuhan yang berbeda terhadap model di sisi hulu. Jika semuanya dikonfigurasi secara manual, setiap kali memasang alat baru, Anda juga harus merawat konfigurasi baru. Berikut empat contoh yang paling umum:

magpie (repositori github.com/yetone/magpie, dengan slogan “Every agent’s model. One place.”) mengatasi masalah ini: pengaturan “Agent mana memakai model apa dan membaca kunci yang mana” dikelola terpusat dalam satu antarmuka. Setelah itu, magpie akan mengubah konfigurasi bawaan tiap alat.

Singkatnya, pembagian tugasnya seperti ini:

• magpie mengatur distribusi: menentukan model yang digunakan Claude Code dan Codex
• Gateway mengatur protokol: meneruskan permintaan berformat Anthropic, OpenAI, atau Gemini ke penyedia model yang sebenarnya

Jadi, Sebaiknya Gateway Hulu Anda Mendukung Banyak Protokol

Kombinasi idealnya adalah “magpie mengatur distribusi, gateway mengatur protokol”. Jika gateway hanya mendukung format yang kompatibel dengan OpenAI, Claude Code perlu lapisan konversi protokol tambahan. Alurnya jadi lebih panjang dan risiko ketidaksesuaian format pemanggilan alat juga meningkat.

APIYI menggunakan pendekatan satu token untuk tiga protokol utama: format kompatibel OpenAI, format native Anthropic, dan format Gemini bisa dipanggil menggunakan kunci yang sama. (Cek cakupan dukungan terbaru di konsol.) Dengan begitu, magpie cukup dihubungkan ke satu layanan hulu dan semua Agent bisa langsung terhubung tanpa perlu mengelola akun maupun tagihan dari masing-masing penyedia.

Memilih di Antara Tiga Cara

Konfigurasi manual memang paling langsung. Namun, semakin banyak alat yang digunakan, semakin tersebar pula kunci di berbagai berkas sehingga biaya rotasi dan penelusuran masalah meningkat. Skrip variabel lingkungan tidak memerlukan dependensi dan bisa dibuat hanya dengan beberapa puluh baris, tetapi Anda tidak bisa menetapkan model yang berbeda untuk tiap Agent. Untuk kebutuhan seperti “Claude Code memakai Claude, Codex memakai GPT, dan Hermes memakai model yang lebih murah”, solusi pengelolaan terpusat seperti magpie jauh lebih praktis.

Langkah 1: Dapatkan kunci API dan salin

1.1 Buat token di konsol APIYI

Buka konsol APIYI (apiyi.com), buat token, lalu salin.

Tidak perlu mengetik perintah apa pun di langkah ini. Sepanjang proses berikutnya, kunci API ini hanya perlu dimasukkan sekali: tempelkan di panel Pemasok magpie (Langkah 3). Setelah ditempel, magpie akan menyiapkan file konfigurasi untuk setiap Agent secara otomatis. Anda tidak perlu menjalankan export untuk variabel lingkungan atau mengubah config.toml, settings.json, dan file lainnya.

🚀 Belum punya token? Daftar di APIYI apiyi.com dan klaim kuota uji coba. Gunakan satu token untuk mencoba beberapa alat yang biasa Anda pakai, lalu tentukan model mana yang ingin digunakan dalam jangka panjang.

1.2 Catat dua alamat ini

Saat mengisi informasi pemasok di Langkah 3, pilih salah satu alamat berikut:

✅ Pemeriksaan langkah ini: Token sudah tersalin dan Anda tahu alamat mana yang harus diisi di Langkah 3.

Langkah 2: Instal magpie dan kenali dua halaman ini

Kode sumber, cara instalasi, dan format konfigurasi magpie mengacu pada README repositori resminya (github.com/yetone/magpie). Proyek ini berkembang cukup cepat, sehingga perintah instalasi dan nama kolom dapat berubah mengikuti versi. Namun, tangkapan layar dan urutan pengoperasian di bawah ini tetap relevan dalam jangka panjang.

Setelah terinstal dan dijalankan, Anda akan melihat jendela dengan navigasi di sisi kiri. Tutorial ini hanya menggunakan dua halaman: Agent (menentukan Agent yang menggunakan model tertentu) dan Pemasok (tempat kunci API disimpan).

① Agent di navigasi kiri adalah “panel kontrol utama” untuk semua Agent Anda:

Gambar 1 · Halaman Agent: setiap alat ditampilkan dalam satu baris. Sakelar di sebelah kanan mengatur apakah alat terhubung ke magpie, sedangkan menu model di sampingnya digunakan untuk memilih model.

Di halaman ini, Anda perlu mengenali tiga hal:

② Pemasok di navigasi kiri adalah tempat untuk memasukkan kunci API dari penyedia upstream (akan dibahas lebih lanjut di bagian berikutnya).

Jika ingin memahami seperti apa file konfigurasi magpie, Anda bisa melihat struktur providers / agents di README resminya. Sederhananya, Anda memberi nama pada penyedia upstream, mengisi base_url dan kunci API, lalu menentukan model untuk setiap Agent. Namun, untuk penggunaan sehari-hari, cukup lakukan semuanya lewat jendela magpie. magpie akan menulis konfigurasi native untuk setiap alat secara otomatis, sehingga lebih aman daripada mengedit YAML secara manual.

✅ Pemeriksaan langkah ini: Jendela magpie dapat dibuka dan Anda melihat menu Agent serta Pemasok di sebelah kiri.

Langkah 3: Tambahkan kunci API di bagian “Penyedia”

3.1 Buka halaman Penyedia

Klik Penyedia di sisi kiri (① dalam kotak merah pada Gambar 2), lalu klik + Tambahkan penyedia di pojok kanan atas (② dalam kotak merah):

Gambar 2 · Halaman Penyedia: buka “Penyedia” dari navigasi di sisi kiri. Tombol “+ Tambahkan penyedia” di pojok kanan atas adalah satu-satunya cara untuk menambahkannya.

Penyedia yang sudah ditambahkan akan muncul sebagai kartu di sini. Baris kedua pada kartu menampilkan alamat dan jumlah model yang tersedia (misalnya, api.apiyi.com · 11 model). Untuk memastikan penyedia bisa digunakan, cek apakah baris ini menampilkan angka.

3.2 Pilih jenis penyedia

Setelah mengeklik “+ Tambahkan penyedia”, Anda akan melihat panel pilihan yang terbagi menjadi beberapa grup (Gambar 3):

Gambar 3 · Panel Tambahkan penyedia: lima jenis sumber—langganan, penyedia, proksi, lokal, dan magpie di komputer lain

Grup di panel ini mewakili lima jenis kunci API yang berbeda:

Jika menggunakan APIYI, endpoint yang kompatibel dengan OpenAI termasuk jenis proksi standar. Pilih opsi yang sesuai di grup Proksi. Jika Anda memiliki kunci OpenAI/Anthropic kompatibel khusus, klik + Penyedia kustom di bagian paling bawah (kotak merah pada Gambar 3), lalu masukkan alamat dan kunci API. Isi alamat dengan https://api.apiyi.com/v1 (untuk permintaan native Anthropic, isi dengan https://api.apiyi.com).

Berikut tampilan lengkap panel saat penyedia dibuka. Ada empat bagian yang perlu Anda perhatikan:

Gambar 4 · Halaman konfigurasi penyedia APIYI: di Base URL, pilih protokol terlebih dahulu, lalu masukkan alamat. Accounts digunakan untuk menyimpan kunci API, sedangkan di Models, centang model yang ingin Anda sediakan untuk Agent.

Gambar ini menunjukkan penerapan “satu token, beberapa protokol” yang disebutkan sebelumnya: alamatnya sama-sama https://api.apiyi.com. Pilih Kompatibel dengan Anthropic untuk endpoint native yang dibutuhkan Claude Code, Kompatibel dengan OpenAI untuk endpoint /v1 yang digunakan Codex / Pi / Hermes, atau Kompatibel dengan Gemini untuk Gemini. Anda tidak perlu mengelola tiga penyedia dan tiga kunci API.

Setelah selesai, simpan lalu kembali ke daftar penyedia dan pastikan dua hal: baris kedua kartu menampilkan jumlah model dan tombolnya dalam posisi aktif. Jika terlihat · N model, berarti kunci API dan alamatnya sudah terhubung—ini sekaligus menjadi pemeriksaan mandiri, jadi Anda tidak perlu menjalankan perintah lain.

✅ Verifikasi langkah ini: Kartu penyedia Anda muncul di daftar dan menampilkan teks seperti · N model, bukan “Belum dikonfigurasi”.

Langkah 4: Hubungkan Agent yang sudah terpasang satu per satu

Kembali ke halaman Agent, lalu lakukan tiga hal yang sama untuk setiap alat yang sudah Anda pasang. Halaman ini menampilkan semua Agent yang bisa dihubungkan dengan magpie (daftarnya terus bertambah; alat yang belum dipasang akan menampilkan “CLI tidak ditemukan”). Hubungkan semua alat yang sudah Anda pasang. Tabel di bawah hanya menggunakan empat alat yang paling umum sebagai contoh:

1. Aktifkan tombol di sisi kanan (berubah dari abu-abu menjadi terang)
2. Pilih model di sebelah kanan tombol (jika tidak memilih, model default akan digunakan; model yang dipilih di sini akan ditulis ke konfigurasi alat tersebut)
3. Buka ulang alat sesuai petunjuk (Codex, Claude Code, Pi, dan Hermes biasanya perlu dimulai ulang agar membaca konfigurasi baru)

Gambar 5 · Buka menu pilihan model: opsi pertama, “Default”, membuat Agent menggunakan model bawaannya tanpa melalui magpie. Setiap opsi di bawahnya ditandai “melalui magpie”. Model yang dipilih akan digunakan melalui penyedia upstream.

Berikut beberapa status yang umum. Jika Anda melihat status ini, berarti konfigurasi berjalan ke arah yang benar:

• Sudah terhubung: Konfigurasi sudah ditulis dan akan berlaku setelah alat dibuka ulang
• Belum terhubung · menggunakan pengaturan XXX sendiri: Tombol belum diaktifkan atau model belum dipilih
• Hanya bisa menggunakan model XXX sendiri; magpie tidak dapat dihubungkan: Alat ini (misalnya, Cursor) hanya mengizinkan penggunaan model bawaannya. Ini adalah batasan desain, bukan kesalahan konfigurasi
• CLI tidak ditemukan: Alat ini belum dipasang atau tidak ada di PATH. Pasang alatnya atau tambahkan ke PATH, lalu coba lagi

💡 Ingin menggunakan model berbeda untuk tiap Agent (Claude untuk Claude Code, GPT untuk Codex, dan model yang lebih murah untuk Hermes)? Pilih modelnya masing-masing di langkah ini. Inilah salah satu keunggulan utama magpie dibandingkan “skrip variabel lingkungan”.

✅ Verifikasi langkah ini: Tombol untuk semua alat yang sudah dipasang aktif dan statusnya tidak lagi menunjukkan “Belum terhubung”.

Langkah 5: Jalankan satu perintah untuk menguji setiap Agent

Konfigurasi saja belum cukup—pastikan semuanya berjalan dengan baik. Kirim tugas paling sederhana di setiap alat:

Cara termudah untuk memastikan permintaan benar-benar melewati gateway adalah membuka konsol APIYI dan memeriksa penggunaan/log token ini. Jika ada catatan pemanggilan baru, berarti semua permintaan dari Agent memang masuk menggunakan kunci yang sama.

✅ Kriteria keberhasilan langkah ini: Semua Agent memberikan respons dengan normal, dan catatan pemanggilan terkait terlihat di konsol.

Lampiran: Cara memilih model (pilihan default jika belum yakin)

💡 Sebaiknya jalankan tugas yang sama di berbagai Agent dan model untuk dibandingkan. Dengan satu token yang digunakan bersama, Anda hanya perlu mengganti nama model, sehingga biaya perbandingannya rendah.

Langkah 6 (opsional): konfigurasi apa saja yang ditulis magpie untukmu?

Bagian ini tidak memengaruhi proses menjalankan dan bukan langkah wajib. Untuk penggunaan sehari-hari, kamu tidak perlu mengutak-atik file-file ini. Begitu mengaktifkan sakelar di langkah 4, magpie sudah menulis semua konfigurasi berikut. Bagian ini disertakan hanya untuk dua hal: supaya kamu tahu lapisan mana yang perlu diperiksa jika terjadi masalah, dan agar kamu bisa menyalin konfigurasinya jika suatu saat tidak ingin menggunakan magpie lagi.

Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Endpoint native Anthropic
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# Opsional: tentukan model default (lihat daftar model di konsol)
# export ANTHROPIC_MODEL="<Claude 模型名>"
claude

Kamu juga bisa menuliskannya di kolom env dalam ~/.claude/settings.json agar tidak bergantung pada sesi terminal.

Codex: bagian provider di ~/.codex/config.toml

# ~/.codex/config.toml
model = "<GPT 系列模型名>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # Endpoint yang kompatibel dengan OpenAI
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # Jika model yang dipilih tidak mendukung Responses, ubah menjadi "chat"

wire_api adalah bagian yang paling mudah terlewat. Codex versi terbaru secara default menggunakan protokol Responses. Jika model di sisi gateway hanya menyediakan Chat Completions, kamu harus mengubahnya menjadi chat.

Pi dan Hermes: deklarasikan provider kustom yang kompatibel dengan OpenAI

Caranya sama: isi base_url dengan https://api.apiyi.com/v1, lalu gunakan APIYI_API_KEY sebagai referensi Key. Struktur konfigurasi berbeda-beda tergantung versinya, jadi ikuti dokumentasi resmi masing-masing:

// Pi: deklarasikan provider di konfigurasi model kustom (struktur mengikuti dokumentasi resmi Pi)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<模型名>" }]
    }
  }
}

# Hermes: jalankan hermes model, lalu pilih endpoint kustom yang kompatibel dengan OpenAI,
# isi informasi berikut sesuai petunjuk (atau tulis ke file .env / config di direktori konfigurasi Hermes)
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <模型名>

#!/usr/bin/env bash
# agents-env.sh —— alternatif tanpa magpie: satu Key untuk semua Agent
# Cara pakai: source agents-env.sh
: "${APIYI_API_KEY:?Ekspor APIYI_API_KEY terlebih dahulu}"

# Claude Code (protokol Anthropic)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Variabel umum untuk alat yang kompatibel dengan OpenAI, seperti Codex / Pi / Hermes
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# Pemeriksaan konektivitas
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ Semua Agent sudah diarahkan ke gateway yang sama"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-你的令牌" | head -c 300

Jika terjadi masalah, periksa bagian ini dulu: empat error yang sering muncul

Urutan pemeriksaan selalu dari bawah ke atas: pastikan gateway dan token berfungsi terlebih dahulu (apakah kartu penyedia menampilkan · N model), lalu periksa konfigurasi native masing-masing Agent, dan terakhir periksa lapisan pemetaan magpie. Dengan tiga langkah ini, kamu bisa mengetahui apakah masalahnya ada di sisi upstream, alatnya sendiri, atau lapisan konfigurasi terpadu.

FAQ

Ringkasan 5 menit

• Pembagian tugas: magpie mengatur pemetaan model, gateway meneruskan permintaan sesuai protokol. Masing-masing fokus pada satu tugas.
• Satu kunci API: pilih penyedia yang mendukung banyak protokol agar semua Agent menggunakan satu kunci API dan satu tagihan.
• Urutan penyiapan: buat kunci di konsol → tempel di bagian “Penyedia” → aktifkan Agent → uji satu per satu. Semuanya bisa dilakukan lewat antarmuka, tanpa perintah.
• Urutan pemecahan masalah: gateway → konfigurasi bawaan Agent → lapisan pemetaan magpie, dari bawah ke atas.
• Catatan untuk Claude Code: gunakan ANTHROPIC_AUTH_TOKEN; jangan tambahkan /v1 ke base_url.
• Catatan untuk Codex: wire_api harus sesuai dengan protokol yang didukung model.
• Opsi cadangan: skrip variabel lingkungan (agents-env.sh) juga bisa membuat semua Agent menggunakan satu kunci API.

Jika Anda menggunakan tiga Agent atau lebih, luangkan setengah jam untuk menyiapkan konfigurasi ini. Nantinya, Anda hanya perlu mengubah satu bagian saat berganti model atau merotasi kunci API. Anda bisa memperoleh kredit uji coba melalui APIYI apiyi.com. Mulailah dengan menguji beberapa alat yang paling sering digunakan, lalu sesuaikan model tiap Agent berdasarkan tugasnya.

Bacaan Lanjutan

• 📘 Apakah Workbuddy mendukung pemanggilan dengan format native Claude? Uji langsung 3 penyebab utama dan 6 jenis error content: Baca artikel ini untuk memahami perbedaan format native Anthropic dan format yang kompatibel dengan OpenAI. Artikel ini juga menjelaskan alasan pada langkah 2 mengapa Claude Code harus menggunakan endpoint native.
• 📊 claude-sonnet-5-5 vs claude-opus-5-5: Opus lebih cepat, Sonnet cuma lebih murah? 6 kelompok data mengungkap kombinasi terbaik untuk Agent perusahaan dengan konteks panjang: Baca artikel ini sebelum menentukan model untuk tiap Agent pada langkah 4, agar bisa memutuskan Agent mana yang menggunakan Opus dan mana yang menggunakan model lebih murah.
• ⚠️ Berapa batas konkurensi gemini-4-argon di AI Studio? 5 penyebab umum error 429 dan solusi dalam 6 langkah: Jika beberapa Agent menggunakan kunci API yang sama secara bersamaan hingga terkena pembatasan laju, ikuti 6 langkah pemecahan masalah di sini.
• 🧭 Muncul error “model not found” dari OpenAI? GPT-5.5 dihentikan dari ChatGPT pada 14 Oktober: 5 langkah pemeriksaan dan alternatif: Jika pada langkah 5 muncul pesan “model tidak ditemukan”, pastikan dulu nama model tersebut masih valid.

📚 Referensi

1. GitHub – magpie: Repositori resmi proyek
2. Tautan: github.com/yetone/magpie
3. Keterangan: Ikuti README untuk informasi instalasi, format konfigurasi, dan pembaruan versi.
4. Dokumentasi resmi Claude Code: Variabel lingkungan dan konfigurasi settings
5. Tautan: docs.anthropic.com/en/docs/claude-code
6. Keterangan: Penjelasan resmi tentang variabel seperti ANTHROPIC_BASE_URL.
7. Repositori OpenAI Codex CLI: Konfigurasi config.toml dan model_providers
8. Tautan: github.com/openai/codex
9. Keterangan: Penjelasan tentang provider kustom dan parameter wire_api.
10. Pusat dokumentasi APIYI: Endpoint berbagai protokol dan daftar model
11. Tautan: docs.apiyi.com
12. Keterangan: Panduan integrasi endpoint dengan protokol OpenAI, Anthropic, dan lainnya.

Penulis: Tim Teknis APIYI
Diskusi teknis: Silakan bagikan pengalaman konfigurasi magpie Anda di kolom komentar. Untuk materi integrasi lainnya, kunjungi pusat dokumentasi APIYI di docs.apiyi.com.