Instalasi Pi dan Konfigurasi OmniProxy

Pi adalah asisten terminal berukuran kecil, yaitu program yang dapat berinteraksi dengan Anda langsung melalui baris perintah, membaca berkas, dan menyelesaikan tugas. System prompt-nya singkat dan alat bawaannya juga tidak banyak. Jika memerlukan perintah, alur kerja, atau antarmuka lain, Anda dapat menambahkannya melalui ekstensi. Ekstensi dapat dipahami sebagai komponen yang menambahkan kemampuan pada Pi dan dapat dibagikan kepada orang lain setelah selesai dibuat.

Subagen menyerahkan sebagian tugas kepada asisten lain, sedangkan mode perencanaan menyusun langkah-langkah terlebih dahulu sebelum mulai menjalankannya. Kedua fungsi ini tidak tersedia secara bawaan. Anda dapat meminta Pi membuatnya atau memasang paket yang dibagikan orang lain.

Persiapan sebelum instalasi

macOS dan Linux menggunakan skrip instalasi, yaitu satu perintah yang mengunduh dan memasang secara otomatis. Windows menggunakan perintah PowerShell yang tersedia di halaman utama Pi. PowerShell adalah lingkungan baris perintah bawaan Windows. Pi juga dapat dipasang di WSL, yaitu lingkungan Linux di dalam Windows.

Jika memilih instalasi melalui npm, siapkan Node.js 22.19 atau versi yang lebih baru terlebih dahulu. npm adalah pengelola paket yang digunakan bersama Node.js dan dapat memasang Pi melalui baris perintah.

macOS Linux

install.sh

• Gunakan curl untuk skrip resmi
• Dependensi ditetapkan oleh penginstal
• Gunakan pi update untuk memperbarui

Windows

install.ps1

• Gunakan perintah PowerShell dari situs resmi
• Git for Windows menyediakan Bash
• WSL juga dapat digunakan

Jika sudah memiliki Node

npm

• Memerlukan Node 22.19+
• Nama paketnya adalah pi-coding-agent
• Tambahkan --ignore-scripts

Instalasi dan peluncuran pertama

Di macOS atau Linux, buka terminal lalu jalankan:

curl -fsSL https://pi.dev/install.sh | sh

Di Windows, buka PowerShell lalu jalankan:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Jika Node.js 22.19 atau versi yang lebih baru sudah terpasang, Anda juga dapat menggunakan perintah alternatif dari Quickstart:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Skrip instalasi mungkin berhenti untuk mengajukan pertanyaan saat dijalankan di terminal interaktif. Ikuti petunjuk yang ditampilkan untuk melanjutkan. Jika versi Node yang memenuhi persyaratan sudah tersedia, perintah npm tersebut tidak akan mengajukan pertanyaan. Untuk memasangnya ke direktori lain, tambahkan --prefix /direktori/Anda. Pada 2026-10-09, cara ini memasang Pi 1.1.0.

Instalasi npm normal tidak memerlukan skrip siklus hidup dependensi, yaitu skrip yang dijalankan paket secara otomatis selama proses instalasi. Skrip instalasi akan mengunci dependensi, lalu pembaruan berikutnya dilakukan dengan pi update. Untuk instalasi npm, cara pembaruannya mengikuti pengelola paket yang Anda gunakan. Pengguna Nix memasang Pi dari flake Pi. Flake adalah konfigurasi yang digunakan Nix untuk mendeskripsikan perangkat lunak dan dependensinya. pi update tidak dapat memperbarui instalasi Nix.

Setelah instalasi selesai, pastikan Pi dapat ditemukan oleh terminal:

pi --version

Di Windows, jika Anda ingin model menjalankan perintah Bash, sebagian besar pengguna lokal disarankan memasang Git for Windows. Bash adalah lingkungan perintah yang digunakan Pi untuk menjalankan sebagian perintah. Pi akan mencari shellPath dalam ~/.pi/agent/settings.json, Git Bash di Program Files, lalu bash.exe di PATH, secara berurutan. shellPath digunakan untuk menentukan lokasi Bash, sedangkan PATH adalah daftar direktori yang digunakan sistem untuk mencari perintah.

Setelah Pi dimulai, Anda dapat memasukkan !printf 'Bash is working\n' untuk memeriksanya. Jika berkas dan alat sudah berada di WSL, lakukan instalasi sesuai Quickstart dari dalam lingkungan Linux tersebut.

Selanjutnya, masuk ke folder yang ingin Anda minta Pi periksa atau proses, lalu jalankan:

cd /path/to/folder
pi

Folder ini menjadi cakupan kerja Pi saat ini. Pi menggunakannya untuk menemukan berkas dan konfigurasi, serta mengelompokkan sesi.

Mendapatkan parameter koneksi dari OmniProxy

Siapkan tiga nilai berikut dari OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: salin ID lengkap dari daftar model OmniProxy saat ini

baseUrl adalah alamat endpoint yang digunakan Pi untuk mengirim permintaan dan harus ditulis hingga /v1. apiKey adalah kunci yang digunakan untuk mengakses endpoint. Model ID adalah nama model yang akan dipanggil dan harus disalin secara lengkap dari daftar model OmniProxy saat ini.

Isi api dengan openai-completions seperti dalam contoh endpoint kompatibel. Kolom ini memberi tahu Pi format endpoint yang harus digunakan untuk mengirim permintaan.

Salin seluruh ID model dan pertahankan garis miring yang ada di dalam namanya. Pada 2026-10-09, dua ID pembanding dalam dokumentasi penyedia adalah gemini-3.8-flash dan grok-4.7. Jangan menyalin nama yang tidak tersedia dalam daftar.

Mengisi konfigurasi alat

Konfigurasi model khusus tingkat pengguna Pi disimpan dalam models.json. Berkas ini berada di direktori agent, yang secara bawaan adalah ~/.pi/agent, sehingga lokasi lengkapnya adalah ~/.pi/agent/models.json. Jika variabel lingkungan PI_CODING_AGENT_DIR ditetapkan, Pi akan menggunakan direktori yang ditentukan oleh variabel tersebut. Variabel lingkungan dapat dipahami sebagai nilai konfigurasi yang disediakan sistem agar dapat dibaca oleh program.

Isi sesuai contoh endpoint kompatibel berikut:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers digunakan untuk mencantumkan layanan yang terhubung, sedangkan models digunakan untuk mencantumkan model yang dapat dipilih. id setiap model harus sesuai dengan Model ID lengkap dalam daftar model OmniProxy saat ini. input menunjukkan bahwa konfigurasi ini menggunakan masukan teks.

apiKey dapat ditulis langsung sebagai nilai literal atau sebagai $NAME maupun ${NAME} agar Pi membacanya dari variabel lingkungan. Nilai yang diawali ! akan diperlakukan sebagai perintah dan dijalankan pada setiap permintaan. Jangan melakukan commit kunci asli ke repositori. Jika gateway tidak memvalidasi kunci, Anda dapat mengisi rangkaian karakter placeholder yang hanya digunakan secara lokal. Pada 2026-10-09, berkas berhasil dibaca dengan cara ini.

Membuka /model akan memuat ulang berkas ini. /model adalah menu di Pi untuk melihat dan memilih model. Model khusus tidak akan muncul di /model sebelum Pi dapat mengurai kredensialnya. Setelah memilih model, tekan Ctrl+S untuk menyimpannya sebagai model bawaan bagi sesi baru.

File

models.json

• Direktori default adalah ~/.pi/agent
• Tambahkan satu entri di providers
• Gunakan completions untuk api

Alamat

baseUrl

• Akhiri dengan /v1
• apiKey dapat menggunakan variabel
• id model harus tepat

Pemilihan

/model

• File akan dimuat ulang setelah dibuka
• Pilih model yang baru ditambahkan
• Ctrl+S dapat menyimpan sebagai default

Memverifikasi tugas nyata

Setelah konfigurasi selesai, Anda dapat melakukan pemeriksaan noninteraktif di dalam direktori yang berisi berkas. Noninteraktif berarti Pi tidak memasuki percakapan berkelanjutan dan akan berhenti setelah menyelesaikan satu tugas tersebut. Ganti nilai setelah --model dengan ID lengkap dari daftar OmniProxy saat ini:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Baca baris pertama dari berkas yang saya tentukan. Jangan ubah berkas tersebut."

Di sini, --tools read hanya mengaktifkan alat pembacaan, dan isi tugas juga secara tegas meminta agar berkas tidak diubah. Pada 2026-10-09, Pi 1.1.0 berhasil membaca isi berkas. Balasan pertama memerlukan waktu sekitar dua menit.

Anda juga dapat menggunakan cara interaktif: masuk ke direktori, jalankan pi, lalu pilih model melalui /model. Salah satu contoh tugas dalam Quickstart adalah meminta Pi menjelaskan susunan repositori ini dan cara menjalankan pemeriksaan. Amati apakah Pi membaca berkas dan memberikan penjelasan, lalu periksa sumber dan ID model dalam catatan pemanggilan OmniProxy.

Mulai

pi dapat dibuka

• Gunakan cd untuk masuk ke folder terlebih dahulu
• pi --version menghasilkan keluaran
• Nama model terlihat di bagian bawah antarmuka

Tugas

Direktori sudah dibaca

• Tanyakan bagaimana repositori diatur
• Periksa file yang ditampilkan
• Jangan hanya memeriksa apakah konfigurasi tersimpan

Catatan

Terlihat di gateway

• Sumbernya adalah Pi
• ID model sesuai
• Kunci tetap berada di komputer lokal

Kesalahan umum

• pi tidak ditemukan: buka ulang terminal lalu coba pi --version. Untuk instalasi npm, pastikan direktori bin global tersedia di PATH.
• Model khusus tidak ada di /model: pastikan models.json berada di ~/.pi/agent/, apiKey dapat diurai, lalu buka kembali /model.
• Windows melaporkan bahwa Bash tidak ditemukan: pasang Git for Windows atau tetapkan shellPath dalam ~/.pi/agent/settings.json. Garis miring terbalik dalam JSON harus ditulis dua kali.
• Permintaan ditolak: pastikan api bernilai openai-completions dan baseUrl diakhiri dengan /v1. Jangan mengaktifkan opsi kompatibilitas tambahan hanya karena pihak lain menyatakan layanannya kompatibel.
• ID model tidak valid: salin ulang dari daftar OmniProxy saat ini.

Referensi resmi

Perintah instalasi tersedia di situs Pi dan Quickstart. Informasi berkas model tersedia di Choose a Model dan Configuration. Informasi lingkungan perintah Windows tersedia di Run Pi on Windows. ID model yang digunakan sebagai contoh tersedia di daftar model Gemini dan halaman model xAI.

Ganti setiap placeholder dengan nilai dari konfigurasi OmniProxy Anda sendiri. Jangan pernah menerbitkan kunci asli.

Hasil tersimpan atau HTTP 200 saja tidak membuktikan kompatibilitas Agen penuh. Periksa sumber dan model dalam catatan panggilan OmniProxy.

Sumber resmi · Pi ↗