Tutorial agen coding goose: instalasi, sumber model, pengaturan API, dan biaya

goose adalah agen coding AI sumber terbuka (Apache-2.0) yang dapat membaca file, mengubah file, dan menjalankan perintah di terminal atau aplikasi desktop. Untuk mulai menggunakannya hanya diperlukan tiga langkah: instalasi, memilih sumber model (provider), dan membuka sesi kerja untuk memberinya tugas. goose sendiri gratis; biayanya berasal dari model yang Anda hubungkan. Tutorial ini mengikuti dokumentasi resmi per 1 Oktober 2026 dan menjelaskan instalasi, tiga jalur berbayar, cara menghubungkannya ke endpoint yang kompatibel dengan OpenAI (termasuk jebakan /v1 yang paling sering terjadi), serta operasi umum. Versi terbaru adalah v1.52.0, dirilis pada 23 September 2026.

Pertama, luruskan namanya. Halaman ini membahas agen coding di goose-docs.ai, dengan repositori di aaif-goose/goose, yang sebelumnya bernama block/goose dan pada April 2026 berpindah ke Agentic AI Foundation milik Linux Foundation. Ini bukan goose.ai — itu adalah layanan inferensi terkelola lain, dan harganya tidak berkaitan dengan ini. goose saat ini tidak memiliki antarmuka bahasa Tionghoa Tradisional; nama menu di bawah ditulis sesuai bahasa Inggris aslinya.

Instalasi

Secara resmi tersedia versi desktop (goose Desktop) dan versi baris perintah (goose CLI); keduanya membaca konfigurasi yang sama.

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

Windows dapat mengunduh versi desktop dari situs resmi; untuk CLI, disarankan menjalankan perintah instalasi yang sama di Git Bash (PowerShell juga bisa). Nama paket Homebrew masih block-goose, karena perubahan nama belum sepenuhnya diterapkan pada paket instalasi; ini tidak berarti proyek tersebut masih dimiliki Block.

Peluncuran pertama: pilih sumber model

Saat pertama kali membuka goose Desktop, layar sambutan akan muncul; CLI akan otomatis masuk ke mode konfigurasi (untuk mengubahnya nanti, jalankan goose configure). Opsi yang tercantum di halaman instalasi ada tiga:

• OpenRouter Login — masuk dengan akun OpenRouter dan konfigurasikan model secara otomatis.
• Tetrate Agent Router Service Login — masuk dengan Tetrate; dokumentasi menyatakan bahwa verifikasi otomatis pertama melalui goose mendapatkan kredit gratis $10, berlaku bagi pengguna baru maupun lama.
• Manual Configuration — pilih provider sendiri dan masukkan kunci. Untuk menghubungkan endpoint yang kompatibel dengan OpenAI (misalnya Kunavo), gunakan opsi ini.

Tiga jalur pembayaran, pilih yang tepat sebelum mengatur

Penjelasan jalur ACP berasal dari dokumentasi provider ACP goose, yang juga mengingatkan bahwa ID sesi ACP berbeda dari ID sesi goose, sehingga kolom telemetri mungkin tidak cocok. Jika Anda sudah memiliki langganan dan hanya ingin menghemat biaya API, lihat jalur ini terlebih dahulu.

Menghubungkan endpoint yang kompatibel dengan OpenAI: Host URL tidak menambahkan /v1

Inilah bagian yang paling sering membuat orang tersendat. goose tidak menerima satu base URL lengkap, melainkan membaginya menjadi “host” dan “path”. Menurut dokumentasi provider, OPENAI_HOST adalah “URL endpoint kustom (default api.openai.com)”, OPENAI_BASE_PATH adalah “jalur request yang ditambahkan setelah host (default v1/chat/completions)”, dan saat menghubungkan proxy, OPENAI_HOST harus diatur ke “alamat dasar proxy (tanpa path)”. Contoh dengan Kunavo:

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

Di goose Desktop, lokasinya adalah Settings → Models → Configure providers → OpenAI; di CLI adalah goose configure → Configure Providers → OpenAI. Organization ID dan Project digunakan untuk akun OpenAI milik sendiri, jadi boleh dibiarkan kosong. Jika Host URL ditulis sebagai https://api.kunavo.com/v1, request akan menjadi /v1/v1/chat/completions; dokumentasi sendiri juga menyatakan bahwa “404 biasanya berarti OPENAI_BASE_PATH tidak sesuai untuk proxy Anda” — masalahnya adalah path, bukan kunci. Sebaliknya, jika muncul 401 “No api key passed in”, berarti kunci tidak terbaca, misalnya karena ditulis di config.yaml (goose akan mengabaikannya).

Jalur lain yang lebih rapi adalah menjadikannya provider tersendiri dalam daftar. goose membaca file definisi JSON dari folder custom_providers, dan Kunavo menyediakan file yang dibuat dari daftar harga langsung, yang hanya memuat model yang mendukung tool calling serta hanya menuliskan nama variabel kunci, tanpa kuncinya:

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

Folder Windows adalah %APPDATA%\Block\goose\config\custom_providers\. Setelah diletakkan di sana, Configure providers di goose Desktop akan menampilkan Kunavo; kunci dapat disimpan di keychain sistem, bukan sebagai variabel lingkungan. Menurut kode sumber goose, model dengan ID yang diawali gpt-5 atau gpt-6 menggunakan /v1/responses, sedangkan model lainnya menggunakan /v1/chat/completions; Kunavo menyediakan keduanya. Anda juga dapat membuatnya secara manual: Configure providers → Add Custom Provider, pilih tipe OpenAI Compatible, dan isi URL API dengan https://api.kunavo.com/v1. Halaman konfigurasi lengkap dalam bahasa Inggris ada di panduan integrasi goose.

Penjelasan terus terang: konfigurasi di atas dirangkum dari dokumentasi dan kode sumber goose; Kunavo belum pernah menjalankan endpointnya sendiri dengan goose — belum pernah menjalankan sesi, streaming, atau pertukaran tool. Pertahankan jalur yang saat ini berfungsi bagi Anda, lalu uji terlebih dahulu dengan tugas kecil yang membaca dan menulis file.

Operasi umum

• Membuka sesi kerja:goose session (dapat diberi nama dengan -n 名稱), lalu lanjutkan dengan goose session --resume -n 名稱; goose session list menampilkan riwayat.
• Mengganti mode otorisasi: masukkan /mode di dalam sesi kerja, lalu pilih auto, approve, chat, atau smart_approve. Jika ingin setiap langkah terlebih dahulu meminta persetujuan Anda, gunakan approve.
• Memilih model:goose configure tidak dapat menerima nama model kustom; untuk ID yang tidak ada dalam daftar, masukkan di goose Desktop atau tetapkan GOOSE_MODEL di config.yaml.
• File instruksi proyek: secara default goose membaca .goosehints dan AGENTS.md (dikendalikan oleh CONTEXT_FILE_NAMES); tulis aturan proyek di sana agar dapat dibawa saat berpindah ke agen lain.
• Jangan memilih model yang tidak mendukung tool calling: dokumentasi menyatakan model seperti itu “hanya dapat melakukan penyelesaian percakapan”, dan ekstensi juga harus dinonaktifkan.

Berapa kira-kira biaya satu sesi kerja

Berikut adalah perhitungan token untuk penjelasan, bukan biaya tugas yang diukur dan bukan batas maksimum tagihan. Anggap satu sesi kerja agen secara total mengirim 400.000 token input yang tidak di-cache di antara banyak putaran, dan menerima 25.000 token output (agen mengirim ulang konteks pada setiap putaran, sehingga inputnya sangat besar). Harga satuan diambil dari daftar harga Kunavo, berdasarkan harga per juta token saat ini.

Tentang caching: dokumentasi goose menyatakan bahwa saat menggunakan Claude melalui provider Anthropic, Amazon Bedrock, Databricks, OpenRouter, dan LiteLLM, goose akan otomatis menambahkan penanda cache_control milik Anthropic. Claude yang digunakan melalui provider OpenAI umum tidak termasuk dalam daftar ini, sehingga goose tidak akan menambahkan penanda tersebut; karena itu, tabel di atas mengasumsikan tidak ada diskon caching, sebagai perkiraan konservatif. Jumlah pada daftar harga Kunavo adalah batas bawah penagihan, bukan batas atas: ketika upstream melaporkan biaya, tagihan mengambil nilai yang lebih tinggi antara “jumlah daftar harga” dan “biaya upstream × markup yang berlaku”.

Pembayaran dari Taiwan

Kunavo menggunakan pengisian saldo prabayar dan menagih berdasarkan token, tanpa biaya bulanan. Pengisian minimum adalah $10, checkout menggunakan Stripe, dan di Taiwan tersedia kartu kredit (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay, serta Link; JKO Pay dan LINE Pay tidak termasuk dalam daftar yang tersedia. Lihat penjelasan penagihan, lalu buat akun dan terbitkan kunci. Untuk membandingkan proxy lain, lihat goose alternatives dan goose vs Claude Code dalam bahasa Inggris.

Pertanyaan umum

Diverifikasi pada 1 Oktober 2026: dokumentasi instalasi, provider, provider ACP, perintah CLI, dan variabel lingkungan goose (cabang main aaif-goose/goose), serta versi dan status pengarsipan repositori melalui GitHub API. Kunavo belum pernah benar-benar menggunakan goose untuk mengakses endpointnya sendiri; harga diambil dari daftar harga waktu nyata, dan semua contoh nilai uang hanyalah perhitungan token untuk ilustrasi.