تثبيت pi ماشي معقّد، غير بأمر واحد. الحاجة الوحيدة اللي خاصك تحسم فيها من اللول هي طريقة المصادقة: تستعمل اشتراك عندك، ولا API Key. لتحت غادي ندوزو التثبيت والمصادقة وأول محادثة كاملين.
المفهوم الأساسي: جوج طرق للمصادقة
من بعد ما يتثبت pi، خاصو بيانات اعتماد ديال شي مزوّد خدمة LLM باش يخدم. كاينين جوج طرق للمصادقة، والفرق بيناتهم هو الحاجة الوحيدة اللي خاصك تفهم فهاد المقال:
الدخول بالاشتراك (/login)｜API Key
شنو تستعمل｜اشتراكات Claude Pro/Max وChatGPT Plus/Pro وغيرها｜API Key كيعطيه المزوّد
الفوترة｜معقّدة (رصيد الاشتراك + استهلاك إضافي محتمل)｜حسب token، كتخلّص على قدّ الاستعمال
فين كتتخزّن بيانات الاعتماد｜~/.pi/agent/auth.json (رمز OAuth كيتجدّد أوتوماتيكياً)｜متغيّرات البيئة أو auth.json
لمن مناسبة｜للي عندو اشتراك وما باغيش يسيّر Key بوحدو｜للي باغي يتحكّم فالمصاريف بدقّة
ملاحظة: الدخول باشتراك Anthropic (Claude Pro/Max) كيدوز عبر قناة harness خارجية، وكيتم الحساب حسب token، وما كيستهلكش رصيد الاشتراك. pi غادي يطلع تحذير، وهادشي عادي. إلا بغيتي تحكّم كامل وتشوف فكل وقت شحال صرفتي، API Key أريح.
التطبيق العملي
1. ثبّت pi
pi خدام فوق Node.js، وخاصو الإصدار 22.19.0 أو أحدث، تأكّد أولاً باستعمال node --version. اختار طريقة من هاد الجوج:
# تثبيت عام باستعمال npm (--ignore-scripts كيتجاوز سكريبتات التبعيات، وكيكون أكثر أماناً)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# أو استعمل مُثبّت curl (إلا ما كانش Node مثبت، غادي يثبّتو ليك)
curl -fsSL https://pi.dev/install.sh | shمن بعد التثبيت، تأكّد باستعمال pi --version. وللحذف استعمل npm uninstall -g @earendil-works/pi-coding-agent.
2. إعداد المصادقة
الطريقة الأولى: API Key (موصى بها)، حطّ الـ Key فمتغيّر بيئة:
export ANTHROPIC_API_KEY=sk-ant-...
piولا دخل لـ pi واستعمل /login واختار واحد API Key provider، وخزّن الـ Key فـ ~/.pi/agent/auth.json (بصلاحيات 0600، غير نتا اللي تقدر تقرا وتكتب فيه). متغيّرات البيئة ديال المزوّدين المعروفين:
المزوّد｜متغيّر البيئة
Anthropic｜ANTHROPIC_API_KEY
OpenAI｜OPENAI_API_KEY
DeepSeek｜DEEPSEEK_API_KEY
Google Gemini｜GEMINI_API_KEY
Groq｜GROQ_API_KEY
xAI｜XAI_API_KEY
OpenRouter｜OPENROUTER_API_KEY
كاينة لائحة كاملة فيها عشرات المزوّدين، شوف وثائق Providers الرسمية[1].
الطريقة الثانية: الدخول بالاشتراك، إلا كان عندك اشتراك بحال Claude Pro ولا ChatGPT Plus، دخل لـ pi واستعمل /login واختار الـ provider المناسب، ودوز عملية OAuth. منين يسالي token، pi كيجددو أوتوماتيكياً. الاختيارات المتاحة: Claude Pro/Max، ChatGPT Plus/Pro(Codex)، GitHub Copilot، xAI، OpenRouter. ولتسجيل الخروج استعمل /logout.
المجتمع ديال Pi نشيط بزاف، وآخر إصدار من Pi Agent ولا كيدعم حتى token plan ديال Qwen.
منين تكمّل إعداد النموذج، تقدر تستعمل /model باش تختار النموذج اللي بغيتي.
Pi Agent فيه حتى مفهوم scoped models.
الهدف من scoped models هو يخلي المستخدم يبدّل بسرعة بين شي نماذج باستعمال ctrl + p. وتقدر حتى تستعمل ctrl + l باش تختار. الإعداد المقابل كاين فالحقل enabledModels داخل الملف ~/.pi/agent/settings.json.
3. أول تشغيل
دخل لمجلد المشروع وشغّل:
cd /path/to/your/project
piأول مرة تدخل لمشروع فيه إعدادات .pi/، pi غادي يسولك واش كتوثق فيه. الموارد ديال المشروع تقدر تحتوي على إضافات كتقدر تنفّذ أي كود، وpi ما كيخليكش تحملها بلا ما تكون عارف. قرار الثقة كيتخزّن فـ ~/.pi/agent/trust.json، ومن بعد ما غاديش يعاود يسولك.
الواجهة مقسّمة من الفوق للتحت لأربع خانات: Header (اختصارات لوحة المفاتيح والموارد المحمّلة)، Messages، Editor (فين كتكتب، ولون الإطار كيمثّل مستوى التفكير)، وFooter (المجلد/الجلسة/استهلاك token/المصاريف/النموذج الحالي). غير كتب وضغط Enter، مثلاً:
شوف ليا بنية هاد المستودع، وقولي كيفاش نشغّل الفحوصات ديالو.pi كيعطي للنموذج افتراضياً أربعة ديال الأدوات: read، write، edit، وbash. وكاينين ثلاثة أدوات أخرى للقراءة فقط، وهي grep/find/ls، ولكن معطّلين افتراضياً. إلا احتجتيهم فعّلهم باستعمال --tools، مثلاً باش يدير pi مراجعة للكود بلا ما يكتب فيه:
pi --tools read,grep,find,ls -p "راجع جودة الكود ديال هاد المستودع"بدّل النموذج بـ Ctrl+L أو /model؛ خرج بضغطتين على Ctrl+C أو باستعمال /quit؛ وكمل من آخر محادثة باستعمال pi -c.
فهم المبدأ
ترتيب تحليل المصادقة: إلا كانو مهيّئين فآن واحد متغيّر بيئة وauth.json ومعاملات سطر الأوامر، pi كيستعملهم بهاد الترتيب: سطر الأوامر --api-key > auth.json > متغيّر البيئة > models.json. إلا بغيتي تجرّب Key مؤقتاً استعمل مباشرة pi --api-key xxx، بلا ما تبدّل ملفات الإعداد.
ثقة المشروع هي حارس للإدخال، ماشي sandbox: كتطلع غير عند التشغيل التفاعلي، أما الوضع غير التفاعلي (pi -p) فالإعداد الافتراضي ديالو هو ask، وتقدر تبدّلو بـ -a/-na. pi ما فيهش sandbox افتراضياً، وإذا كان عند النموذج bash يقدر ينفّذ أي أمر. فالتعامل مع مستودعات ما موثوقاش، خاصك العزل باستعمال container؛ وهادشي غادي نهضرو عليه فمقال الأمان من بعد.
مشاكل شائعة
س: pi --version كيعطي command not found، ولكن npm كيقول راه تثبّت.
غالباً مجلد bin العام ديال npm ما داخلش فـ PATH. استعمل npm prefix -g باش تعرف المسار وزيدو لـ PATH، وإلا كنت كتستعمل nvm ما تنساش nvm use.
س: عند التشغيل كيقولي إن إصدار Node قديم بزاف.
pi خاصو Node 22.19.0+، حدّثو باستعمال مدير إصدارات بحال fnm/mise/nvm، ولا خلّي مُثبّت curl يثبّتو ليك.
س: من بعد تسجيل الدخول بـ Claude Pro كيبقى كيطّلع تحذير الاستهلاك الإضافي كل مرة.
اشتراك Anthropic كيدوز عبر قناة خارجية وكيتم الحساب حسب token. إلا بغيتي تحيّدو، زيد هاد الإعداد فـ ~/.pi/agent/settings.json:
{ "warnings": { "anthropicExtraUsage":false } }س: Shift+Enter ما كيبدّلاش السطر.
pi كيستعمل بروتوكول لوحة مفاتيح Kitty باش يتعرّف على مفاتيح التعديل. iTerm2 وKitty وGhostty خدامين بلا إعدادات إضافية، وVS Code 1.109.5+ كيدعمو افتراضياً. أما Windows Terminal وWezTerm وAlacritty خاصك تزيد يدوياً سطر فالإعدادات باش تحوّل ضغطات المفاتيح؛ شوف وثائق إعدادات الطرفية[2].
س: بغيت نخدم بلا إنترنت نهائياً، وما نتاصلش بـ pi.dev باش نقلب على التحديثات.PI_OFFLINE=1 كيوقف جميع عمليات الشبكة عند التشغيل. وإذا بغيتي غير توقف البحث عن الإصدار استعمل PI_SKIP_VERSION_CHECK=1.
مراجع
• وثائق البداية السريعة ديال Pi[3]
• وثائق Pi Providers[1] - جميع Provider ومتغيّرات البيئة وإعدادات مزوّدي السحابة
• وثائق Pi Custom Models[4] - تخصيص Provider باستعمال models.json
• وثائق Pi Settings[5]
• Pi Terminal Setup[2] - إعداد أزرار مختلف الطرفيات
• مستودع Pi على GitHub[6]
روابط الاقتباس
[1] وثائق Providers الرسمية: https://pi.dev/docs/latest/providers[2] وثائق إعدادات الطرفية: https://pi.dev/docs/latest/terminal-setup[3] وثائق البداية السريعة ديال Pi: https://pi.dev/docs/latest/quickstart[4] وثائق Pi Custom Models: https://pi.dev/docs/latest/models[5] وثائق Pi Settings: https://pi.dev/docs/latest/settings[6] مستودع Pi على GitHub: https://github.com/earendil-works/pi