Torna alle skill
setup-gateway
di Sinholms
Codex—Non ancora valutato
La tua valutazione
Sintesi
Konfigurator gateway OpenAI-compatible untuk Claude Code, OpenCode, dan Codex CLI. Zero-dependency, interaktif + CI, backup atomik + restore, config preservation, selftest built-in.
Descrizione
<div align="center"> # 🛰️ setup-gateway **Konfigurator gateway OpenAI-compatible untuk Claude Code, OpenCode, dan Codex CLI — sekali jalan, config ter-update dengan aman.** [](#) [](#) [](#) [](#) [](#) [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.
Installazione
Installa la skill da https://github.com/Sinholms/setup-gatewayQuesta skill non è pubblicata sul registro ClawHub. Incolla il prompt nel tuo agente di coding — Claude Code, Cursor, Codex — e installerà la skill direttamente dal repository sorgente.
Apri il repository