نصب Pi و پیکربندی OmniProxy

Pi یک دستیار ترمینال کوچک است—برنامه‌ای که مستقیماً در خط فرمان با شما صحبت می‌کند، فایل‌ها را می‌خواند و کارها را انجام می‌دهد. این ابزار دارای یک پرامپت سیستمی کوتاه و به طور پیش‌فرض فقط چند ابزار است. اگر به دستورات، گردش‌های کاری یا رابط‌های کاربری دیگری نیاز دارید، می‌توانید بعداً آن‌ها را از طریق افزونه‌ها اضافه کنید. افزونه‌ها مؤلفه‌هایی هستند که قابلیت‌هایی را به Pi اضافه می‌کنند و پس از ایجاد، می‌توانید آن‌ها را با دیگران به اشتراک بگذارید.

زیر-عامل‌ها (Subagents) بخشی از یک کار را به دستیار دیگری محول می‌کنند، در حالی که حالت برنامه‌ریزی (plan mode) مراحل را پیش از شروع اجرا سازماندهی می‌کند. هیچ‌کدام از این ویژگی‌ها به طور پیش‌فرض گنجانده نشده‌اند، اما می‌توانید از Pi بخواهید آن‌ها را بسازد یا بسته‌های به اشتراک گذاشته شده توسط دیگران را نصب کنید.

پیش از شروع

macOS و لینوکس از یک اسکریپت نصب استفاده می‌کنند—یک دستور واحد که به طور خودکار Pi را دانلود و نصب می‌کند. در ویندوز، از دستور PowerShell ارائه شده در صفحه اصلی Pi استفاده کنید. PowerShell محیط خط فرمان موجود در ویندوز است. شما همچنین می‌توانید Pi را در WSL، محیط لینوکس موجود در ویندوز، نصب کنید.

اگر انتخاب می‌کنید با npm نصب کنید، به Node.js 22.19 یا بالاتر نیاز دارید. npm مدیر بسته مورد استفاده با Node.js است و می‌تواند Pi را از خط فرمان نصب کند.

macOS لینوکس

install.sh

• اجرای اسکریپت رسمی با curl
• نصب‌کننده وابستگی‌ها را پین می‌کند
• به‌روزرسانی با pi update

ویندوز

install.ps1

• دستور رسمی PowerShell
• Git for Windows محیط Bash را فراهم می‌کند
• همچنین می‌توانید از WSL استفاده کنید

Node از قبل نصب شده است

npm

• نیاز به Node 22.19+ دارد
• نام بسته pi-coding-agent است
• افزودن --ignore-scripts

نصب و اولین اجرای Pi

در macOS یا لینوکس، یک ترمینال باز کنید و اجرا کنید:

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

در ویندوز، PowerShell را باز کنید و اجرا کنید:

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

اگر Node.js 22.19 یا بالاتر از قبل نصب شده است، می‌توانید از دستور جایگزین در «شروع سریع» نیز استفاده کنید:

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

اسکریپت نصب ممکن است برای پرسیدن سوالات در یک ترمینال تعاملی متوقف شود. برای ادامه، دستورالعمل‌های روی صفحه را دنبال کنید. اگر نسخه سازگاری از Node دارید، این دستور npm سوالی نخواهد پرسید. برای نصب Pi در دایرکتوری دیگر، --prefix /your/directory را اضافه کنید. در تاریخ 2026-10-09، این دستور Pi 1.1.0 را نصب کرد.

یک نصب معمولی npm به اسکریپت‌های چرخه حیات وابستگی نیاز ندارد، که اسکریپت‌هایی هستند که بسته‌ها به طور خودکار در حین نصب اجرا می‌کنند. اسکریپت نصب وابستگی‌ها را پین می‌کند؛ پس از آن، Pi را با pi update به‌روزرسانی کنید. برای نصب npm، از روش به‌روزرسانی ارائه‌شده توسط مدیر بسته خود استفاده کنید. کاربران Nix باید از flake مربوط به Pi نصب کنند. flake یک پیکربندی Nix است که نرم‌افزار و وابستگی‌های آن را توصیف می‌کند و pi update نمی‌تواند نصب Nix را به‌روزرسانی کند.

پس از نصب، ابتدا تأیید کنید که ترمینال شما می‌تواند Pi را پیدا کند:

pi --version

در ویندوز، اگر می‌خواهید مدل‌ها دستورات Bash را اجرا کنند، نصب Git for Windows برای اکثر کاربران محلی توصیه می‌شود. Bash محیط دستوری است که Pi برای اجرای برخی دستورات استفاده می‌کند. Pi تنظیمات shellPath را در ~/.pi/agent/settings.json، سپس Git Bash در Program Files و سپس bash.exe در PATH را به ترتیب بررسی می‌کند. shellPath مکان Bash را مشخص می‌کند، در حالی که PATH لیستی از دایرکتوری‌هایی است که سیستم برای دستورات جستجو می‌کند.

پس از شروع Pi، می‌توانید !printf 'Bash is working\n' را وارد کنید تا آن را بررسی کنید. اگر فایل‌ها و ابزارهای شما از قبل در WSL هستند، Pi را در آن محیط لینوکس با دنبال کردن «شروع سریع» نصب کنید.

سپس، وارد پوشه‌ای شوید که می‌خواهید Pi آن را بررسی کند یا روی آن کار کند، و سپس آن را شروع کنید:

cd /path/to/folder
pi

این پوشه به محدوده کاری فعلی Pi تبدیل می‌شود. Pi از آن برای کشف فایل‌ها و پیکربندی و گروه‌بندی جلسات استفاده می‌کند.

دریافت مقادیر اتصال از OmniProxy

ابتدا، این سه مقدار را از OmniProxy دریافت کنید:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl نقطه پایانی API است که Pi درخواست‌ها را به آن می‌فرستد و باید شامل /v1 باشد. apiKey کلیدی است که برای دسترسی به API استفاده می‌شود. Model ID نام مدلی است که باید فراخوانی شود و باید به طور کامل از لیست مدل‌های فعلی OmniProxy کپی شود.

همانطور که در مثال API سازگار نشان داده شده است، api را روی openai-completions تنظیم کنید. این فیلد به Pi می‌گوید هنگام ارسال درخواست‌ها از کدام فرمت API استفاده کند.

شناسه کامل مدل را کپی کنید، شامل هرگونه اسلش در نام. در تاریخ 2026-10-09، دو شناسه مرجع در مستندات ارائه‌دهنده gemini-3.8-flash و grok-4.7 بودند. نامی را که در لیست وجود ندارد کپی نکنید.

وارد کردن پیکربندی ابزار

پیکربندی مدل سفارشی در سطح کاربر در Pi در models.json ذخیره می‌شود. این فایل در دایرکتوری عامل قرار دارد که به طور پیش‌فرض ~/.pi/agent است، بنابراین مسیر کامل آن ~/.pi/agent/models.json می‌باشد. اگر متغیر محیطی PI_CODING_AGENT_DIR تنظیم شده باشد، Pi به جای آن از دایرکتوری مشخص شده توسط آن متغیر استفاده می‌کند. متغیر محیطی یک مقدار پیکربندی است که توسط سیستم برای خواندن برنامه‌ها ارائه می‌شود.

پیکربندی را همانطور که در مثال API سازگار نشان داده شده است وارد کنید:

{
  "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 سرویس‌های متصل را فهرست می‌کند، در حالی که models مدل‌هایی را که می‌توان انتخاب کرد فهرست می‌کند. id هر مدل باید با شناسه کامل مدل در لیست فعلی OmniProxy مطابقت داشته باشد. input نشان می‌دهد که مدل در اینجا برای ورودی متن پیکربندی شده است.

apiKey می‌تواند به عنوان یک مقدار ثابت متنی وارد شود، یا به عنوان $NAME یا ${NAME} تا Pi آن را از یک متغیر محیطی بخواند. مقداری که با ! شروع می‌شود به عنوان یک دستور در نظر گرفته شده و برای هر درخواست اجرا می‌شود. یک کلید واقعی را در مخزن (repository) قرار ندهید. اگر درگاه کلیدها را اعتبارسنجی نمی‌کند، می‌توانید یک رشته جایگزین که فقط در رایانه محلی شما استفاده می‌شود وارد کنید. در تاریخ 2026-10-09، Pi فایل را با این پیکربندی با موفقیت خواند.

باز کردن /model این فایل را دوباره بارگذاری می‌کند. /model رابط کاربری در Pi برای مشاهده و انتخاب مدل‌ها است. مدل‌های سفارشی تا زمانی که Pi نتواند اعتبار آن‌ها را حل کند، در /model ظاهر نمی‌شوند. پس از انتخاب یک مدل، Ctrl+S را فشار دهید تا آن را به عنوان مدل پیش‌فرض برای جلسات جدید ذخیره کنید.

فایل

models.json

• دایرکتوری پیش‌فرض: ~/.pi/agent
• افزودن یک ورودی زیر providers
• تنظیم api روی completions

آدرس

baseUrl

• شامل /v1
• apiKey می‌تواند به یک متغیر ارجاع دهد
• شناسه مدل باید دقیق باشد

انتخاب

/model

• باز کردن آن فایل را دوباره بارگذاری می‌کند
• انتخاب مدلی که تازه اضافه کردید
• Ctrl+S آن را به عنوان پیش‌فرض ذخیره می‌کند

تأیید با یک کار واقعی

پس از تکمیل پیکربندی، می‌توانید یک بررسی غیرتعاملی در دایرکتوری حاوی فایل‌ها انجام دهید. حالت غیرتعاملی به این معنی است که Pi این کار واحد را تکمیل کرده و سپس به جای ورود به یک مکالمه مداوم، خارج می‌شود. مقدار بعد از --model را با شناسه کامل از لیست فعلی OmniProxy جایگزین کنید:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Read the first line of the file you specify. Do not modify the file."

در اینجا، --tools read فقط ابزار خواندن را فعال می‌کند و کار همچنین صراحتاً به Pi دستور می‌دهد که فایل را تغییر ندهد. در تاریخ 2026-10-09، Pi 1.1.0 محتویات فایل را با موفقیت خواند. اولین پاسخ حدود دو دقیقه طول کشید.

شما همچنین می‌توانید از حالت تعاملی استفاده کنید: وارد دایرکتوری شوید، pi را اجرا کنید و سپس یک مدل را با /model انتخاب کنید. یک مثال از کار در «شروع سریع» از Pi می‌خواهد توضیح دهد که مخزن چگونه سازماندهی شده است و چگونه می‌توان بررسی‌های آن را اجرا کرد. مشاهده کنید که آیا فایل‌ها را می‌خواند و توضیحی ارائه می‌دهد، سپس منبع و شناسه مدل را در لاگ‌های درخواست OmniProxy تأیید کنید.

راه‌اندازی

pi راه‌اندازی می‌شود

• ابتدا cd به پوشه
• pi --version خروجی تولید می‌کند
• نام مدل در پایین رابط ظاهر می‌شود

کار

دایرکتوری را خواند

• بپرسید مخزن چگونه سازماندهی شده است
• فایل‌هایی را که فهرست می‌کند بررسی کنید
• فقط به ذخیره موفق پیکربندی تکیه نکنید

لاگ‌ها

در درگاه قابل مشاهده است

• منبع Pi است
• شناسه مدل مطابقت دارد
• کلید را روی رایانه محلی نگه دارید

خطاهای رایج

• pi پیدا نمی‌شود: ترمینال را دوباره باز کنید و دوباره pi --version را امتحان کنید. برای نصب npm، تأیید کنید که دایرکتوری bin جهانی در PATH قرار دارد.
• مدل‌های سفارشی در /model ظاهر نمی‌شوند: تأیید کنید که models.json در ~/.pi/agent/ است، بررسی کنید که apiKey قابل حل است و سپس /model را دوباره باز کنید.
• ویندوز گزارش می‌دهد که Bash پیدا نمی‌شود: Git for Windows را نصب کنید، یا shellPath را در ~/.pi/agent/settings.json تنظیم کنید. اسلش‌های معکوس در JSON باید دو بار نوشته شوند.
• درخواست رد می‌شود: بررسی کنید که api برابر با openai-completions باشد و baseUrl با /v1 پایان یابد. صرفاً به این دلیل که سرویس خود را سازگار توصیف می‌کند، گزینه‌های سازگاری اضافی را فعال نکنید.
• شناسه مدل نامعتبر است: آن را دوباره از لیست فعلی OmniProxy کپی کنید.

مراجع رسمی

برای دستورات نصب، به وب‌سایت Pi و شروع سریع مراجعه کنید. برای فایل مدل، به انتخاب یک مدل و پیکربندی مراجعه کنید. برای محیط دستوری ویندوز، به اجرای Pi در ویندوز مراجعه کنید. برای شناسه‌های مدل استفاده شده در مثال‌ها، به لیست مدل Gemini و صفحه مدل‌های xAI مراجعه کنید.

هر جایگاه را با مقادیر از پیکربندی OmniProxy خود جایگزین کنید. هرگز یک کلید واقعی را منتشر نکنید.

یک نتیجه ذخیره شده یا HTTP 200 به تنهایی سازگاری کامل عامل را اثبات نمی‌کند. منبع و مدل را در گزارش درخواست OmniProxy بررسی کنید.

منابع رسمی · Pi ↗