🛰️ setup-gateway

Konfigurator gateway OpenAI-compatible untuk Claude Code, OpenCode, dan Codex CLI — sekali jalan, config ter-update dengan aman.

Quick start · Cara kerja · Perintah · Flag & env · Keamanan · Troubleshooting

Tulis ulang config alat AI kamu tanpa merusak yang sudah ada — backup otomatis, preservasi setting, dan restore satu perintah.

setup-gateway adalah CLI generik yang mengkonfigurasi gateway API OpenAI-compatible (LiteLLM, OpenRouter, proxy internal perusahaan, instance 9Router lokal, dll.) ke tiga klien AI coding populer. Tidak ada provider, base URL, atau model yang di-hardcode — kamu memasukkan base URL + API key + model sendiri tiap setup.

Satu perintah. Pilih tool → tempel base URL → tempel key → pilih model → selesai. Config lama dipertahankan, backup dibuat, dan kamu bisa kembali kapan pun dengan restore.

✨ Kenapa menarik

• 🧩 Generik & netral — pakai gateway apa pun yang expose /v1 (Responses API untuk Codex).
• 🧰 Tiga tool sekaligus — Claude Code (settings.json), OpenCode (opencode.json), Codex CLI (config.toml).
• 🖱️ Interaktif (menu panah, filterable model picker, multi-select catalog) dan headless/CI (flag + env) — satu binary, dua dunia.
• 🧼 Preservasi config — hanya bagian gateway yang disentuh; komentar TOML, provider lama, agent.*, dan key tak dikenal tetap utuh.
• 💾 Backup atomik + restore — salah menulis bukan masalah, karena setiap tulis didahului backup berlabel waktu.
• 🧪 Selftest built-in — verifikasi fungsi murni tanpa menyentuh disk nyata (--selftest, cocok untuk CI).
• 🪶 Zero-dependency — Node ≥ 18 saja (fetch, readline, AbortController bawaan). Tidak ada npm install.

🚀 Quick start

Butuh Node ≥ 18. Clone, lalu jalankan:

# interaktif — menu pilih tool → tanya base URL, API key, model
node bin/setup-gateway.mjs
# alias:  node setup-gateway.mjs      (shim, setara)
# alias:  npm run setup

Langsung satu tool:

node bin/setup-gateway.mjs claude     # Claude Code
node bin/setup-gateway.mjs opencode   # OpenCode
node bin/setup-gateway.mjs codex      # Codex CLI

Headless / CI (tanpa prompt):

node bin/setup-gateway.mjs claude \
  --base-url https://gw.example.com \
  --api-key sk-... \
  --model deepseek-v4 \
  --yes

status (read-only) dan restore (pulihkan backup) tersedia kapan pun:

node setup-gateway.mjs status         # lihat config aktif (key termask)
node setup-gateway.mjs restore codex  # pulihkan backup terakhir Codex

⚙️ Cara kerja

Alur interaktif:

1. Pilih tool (panah + spasi; a = semua).
2. Masukkan Base URL — mis. https://gw.example.com atau http://127.0.0.1:8080.
3. Masukkan API key.
4. Pilih model — tool mencoba GET <baseURL>/v1/models dengan key sebagai Bearer. Berhasil → daftar filterable (ketik untuk cari); gagal/timeout → ketik id model manual.
5. Config ditulis → backup dibuat → (khusus Claude Code) suffix key di-approve di ~/.claude.json supaya tidak ada prompt izin custom API key.

Yang dihasilkan per tool:

Contoh config.toml yang dihasilkan untuk Codex:

model = "deepseek-v4"
model_provider = "gateway"
model_catalog_json = "C:/Users/you/.codex/gateway-catalog.json"

[model_providers.gateway]
name = "Gateway"
base_url = "https://gw.example.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-..."

Yang tidak disentuh: setting/env lain dipertahankan (mis. ANTHROPIC_AUTH_TOKEN, ANTHROPIC_DEFAULT_*_MODEL, provider lama, blok agent, komentar TOML, dan key top-level Codex lain seperti model_reasoning_effort).

Catatan khusus Codex

• wire_api = "responses" wajib. Sejak awal 2026 Codex hanya mendukung OpenAI Responses API (/v1/responses). Gateway yang hanya menyediakan Chat Completions klasik tidak akan jalan langsung; gunakan proxy translasi (mis. LiteLLM) bila perlu.
• API key ditulis langsung via experimental_bearer_token (konsisten dengan Claude/OpenCode yang juga menulis key di config). Codex resmi merekomendasikan env_key (key di env var, bukan config), tapi tulis-langsung didukung dan lebih sesuai filosofi tool ini.
• Provider id reserved openai, ollama, lmstudio tidak boleh dipakai sebagai --provider-name (ditolak dengan error). Pilih nama lain (default: gateway).
• Config project-scoped (.codex/config.toml di repo) sengaja tidak bisa mengoverride provider/auth oleh desain Codex — tool ini selalu menulis ke config user-level (~/.codex/config.toml / $CODEX_HOME).
• Model catalog /model picker — selain set model default, saat setup Codex tool menulis gateway-catalog.json di direktori config dan menunjuknya lewat key top-level model_catalog_json. Efeknya model gateway muncul di picker bawaan Codex (/model), jadi ganti model cukup lewat /model tanpa re-run tool ini. Mode interaktif: multi-select model tambahan (spasi centang, a semua, default model utama tercentang). CI/--yes: catalog berisi model utama saja. Butuh restart Codex sekali setelah setup agar catalog aktif. Catalog butuh Codex ≥ 0.105.0 (key model_catalog_json resmi sejak versi itu).

🛠️ Perintah

🧩 Flag & env

Flag -- yang tidak dikenal → error (tidak diam-diam).

Env vars: GATEWAY_BASE_URL, GATEWAY_API_KEY, GATEWAY_MODEL. Precedence nilai: flag → env → prompt (TTY) → error non-interaktif (dengan pesan flag/env yang harus diisi). Tidak ada default hardcoded.

🔒 Keamanan

• API key disimpan plaintext di file config — ini format yang dipakai tool itu sendiri, tapi sadari risikonya. status selalu menampilkan key termask.
• Base URL http:// → peringatan keras + konfirmasi y/N (atau butuh --yes di non-TTY) karena key dikirim tanpa TLS. Untuk gateway lokal dev (http://127.0.0.1:...) ini normal dan didukung.
• Tool mengirim key hanya ke dua tempat: GET <baseURL>/v1/models (ambil daftar model) dan file config itu sendiri. Tidak ada telemetri, tidak ada endpoint lain.
• restore tidak mengubah ~/.claude.json (suffix approval yang tersisa tidak berbahaya; menghapusnya justru bisa memecah key yang sudah di-approve).

💾 Backup & restore

Setiap kali menulis config, isi lama disalin dulu ke file di direktori yang sama:

settings.json.backup-2026-08-04T18-52-00.json
opencode.json.backup-2026-08-04T18-52-00.json
config.toml.backup-2026-08-04T18-52-00.toml

(Stempel waktu ISO, aman Windows — tanpa :/.)

node setup-gateway.mjs restore             # menu pilih tool
node setup-gateway.mjs restore claude      # TTY = menu pilih backup, --yes = terbaru
node setup-gateway.mjs restore codex       # pulihkan config.toml

• Tidak ada backup → error, tidak menulis apa pun.
• Backup bukan file valid (JSON utk Claude/OpenCode, TOML utk Codex) → error, tidak menulis apa pun (file rusak tidak pernah dikembalikan).
• restore membuat backup lagi dari config saat ini sebelum menimpa (jaring pengaman).
• Untuk Codex, restore menulis raw bytes backup apa adanya (tidak parse ulang) supaya komentar & formatting tetap utuh.

🩺 Troubleshooting