Skip to content
TakoAPI
Back to skills

setup-gateway

by Sinholms

Codex
—Not yet rated
Your rating

Brief

Konfigurator gateway OpenAI-compatible untuk Claude Code, OpenCode, dan Codex CLI. Zero-dependency, interaktif + CI, backup atomik + restore, config preservation, selftest built-in.

Description

<div align="center">

# 🛰️ setup-gateway

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

[![Zero dependency](https://img.shields.io/badge/dependencies-0-brightgreen)](#)
[![Node](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white)](#)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](#)
[![Selftest](https://img.shields.io/badge/selftest-pass-brightgreen)](#)
[![Interactive + CI](https://img.shields.io/badge/mode-interactive%20%2B%20CI-informational)](#)

[Quick start](#-quick-start) ·
[Cara kerja](#-cara-kerja) ·
[Perintah](#-perintah) ·
[Flag & env](#-flag--env) ·
[Keamanan](#-keamanan) ·
[Troubleshooting](#-troubleshooting)

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

</div>

---

`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:

```bash
# 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:

```bash
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):

```bash
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:

```bash
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:

```toml
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**:

```text
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 `:`/`.`)

```bash
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

```bash
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.

Installation

Install the skill from https://github.com/Sinholms/setup-gateway

This skill is not published on the ClawHub registry. Paste the prompt into your coding agent — Claude Code, Cursor, Codex — and it will install the skill straight from the source repository.

Open the repository

Links