🛰️ 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:

Tool	File	Isi yang ditulis
Claude Code	~/.claude/settings.json (atau $CLAUDE_CONFIG_DIR)	env.ANTHROPIC_BASE_URL, env.ANTHROPIC_API_KEY, model
OpenCode	~/.config/opencode/opencode.json (atau $OPENCODE_CONFIG_DIR)	blok provider.<nama>, model = <nama>/<model>
Codex CLI	~/.codex/config.toml (atau $CODEX_HOME)	model, model_provider, model_catalog_json, blok [model_providers.<nama>], plus gateway-catalog.json

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

Perintah	Perilaku
(tanpa subcommand)	menu pilih tool → setup tiap tool terpilih
claude / opencode / codex (alias cc/oc/cx)	setup tool itu langsung
status	tampilkan base URL, model, API key (termask) dari config aktif — read-only
restore [claude|opencode|codex]	pulihkan backup terakhir di direktori config (TTY: menu pilih backup)
--help / -h / --version	bantuan / versi
--selftest	uji fungsi murni tanpa menyentuh config (cocok untuk CI)

🧩 Flag & env

Flag	Efek
--base-url <url>	ganti prompt base URL
--api-key <key>	ganti prompt API key
--model <id>	set model default, lewati picker
--provider-name <nama>	nama blok provider (default: gateway)
--yes	terima semua default, lewati menu, dan langsung melewati peringatan http
--skip-backup	jangan buat backup sebelum menulis (risiko kamu tanggung sendiri)
--config-dir <dir>	override CLAUDE_CONFIG_DIR (konflik dengan env = error)
--opencode-config-dir <dir>	override OPENCODE_CONFIG_DIR (konflik dengan env = error)
--codex-config-dir <dir>	override CODEX_HOME (konflik dengan env = error)
--status / --restore	alias subcommand

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

Gejala	Solusi
[x] Flag tidak dikenal: [--x]	Hanya flag yang didukung; lihat tabel di atas.
[x] Base URL wajib diisi...	Non-interaktif butuh --base-url / GATEWAY_BASE_URL.
[x] API key wajib diisi...	Non-interaktif butuh --api-key / GATEWAY_API_KEY.
[x] Model wajib diisi...	Non-interaktif butuh --model / GATEWAY_MODEL.
[x] ... di-reserve Codex (openai/ollama/lmstudio)	Ganti --provider-name ke nama lain (mis. gateway).
Codex: provider returns 404 / unsupported	Pastikan gateway meng-expose Responses API (/v1/responses), bukan hanya Chat Completions.
Codex /model tidak menampilkan model gateway	Pastikan model_catalog_json menunjuk gateway-catalog.json yang ada (status → baris Catalog), lalu restart Codex — catalog dibaca saat startup. Butuh Codex ≥ 0.105.0.
Terjebak raw-mode (terminal mati) setelah menu/Esc	Esc/Ctrl-C normalnya bersih; jika macet, jalankan stty sane (POSIX) atau buka terminal baru. Tool menjaga via input.setRawMode(false) di semua path.
Config jadi berantakan	node setup-gateway.mjs restore claude (atau opencode/codex).
~/.claude.json sudah berisi suffix approval lama	Tidak masalah — suffix baru ditambahkan; idempoten, suffix lama dibiarkan.
restore saat stdin bukan TTY	Butuh tool eksplisit: restore codex + --yes untuk ambil backup terbaru.

🧪 Selftest

node setup-gateway.mjs --selftest
# alias: npm run selftest

Menjalankan puluhan asersi fungsi murni (tanpa menyentuh config nyata) dan exit 0/1 — bagus untuk CI sebelum rilis.

🗺️ Roadmap

• Publikasi ke npm sebagai npx setup-gateway (package.json + bin sudah siap).
• Multi-provider sekaligus dalam satu file OpenCode/Codex (saat ini satu provider per run).

📄 Lisensi

MIT — bebas dipakai, dimodifikasi, didistribusikan.