تثبيت OpenCode وإعداده مع OmniProxy

OpenCode هو مساعد برمجة مفتوح المصدر يتيح لك كتابة الشيفرة من الطرفية أو IDE أو تطبيق سطح المكتب، ولا يحتفظ بشيفرتك أو سياقها، لذا يناسب المشاريع التي تهتم بالخصوصية. يُستخدم build لتعديل المشروع، بينما يكون plan للقراءة فقط افتراضيًا، ما يجعله مناسبًا لفهم الشيفرة غير المألوفة أولًا وتنظيم التعديلات المقترحة. ويمكنك اختيار خدمة النماذج حسب احتياجاتك.

التحضير قبل التثبيت

يُعد سكربت التثبيت الخيار الأسهل. تحتاج إلى طرفية حديثة يمكنها تشغيل الأوامر والتعامل مع ملفات المشروع، مثل WezTerm أو Alacritty أو Ghostty أو Kitty. على Windows، يُفضّل استخدام WSL، وهي أداة لتشغيل بيئة Linux داخل Windows وتوفر أداءً ووظائف أكثر اكتمالًا.

الأسهل

برنامج التثبيت النصي

• curl opencode.ai/install
• استخدمه مباشرةً على macOS وLinux
• يُنصح باستخدام WSL على Windows

macOS وLinux

Homebrew tap

• anomalyco/tap/opencode
• يُحدّث بوتيرة أعلى من الصيغة
• تتوفر حزمة أيضًا لـ Arch

Windows الأصلي

مدير الحزم

• choco أو scoop
• أو التثبيت العام باستخدام npm
• يمكن أيضًا التنزيل من Releases

جهّز أيضًا معرّف النموذج الموجود في قائمة النماذج الحالية. معرّف النموذج هو الاسم الذي تستخدمه الخدمة للتعرّف بدقة على نموذج معين.

التثبيت والتشغيل لأول مرة

أسهل أمر للتثبيت هو:

curl -fsSL https://opencode.ai/install | bash

يمكن أيضًا استخدام طرق التثبيت التالية:

• Node.js: ‏npm install -g opencode-ai. تتوفر أيضًا أوامر تثبيت عامة مقابلة لكل من Bun وpnpm وYarn، ويمكن العثور عليها في صفحة التعريف الموجودة في نهاية الدليل.
• Homebrew على macOS وLinux: ‏brew install anomalyco/tap/opencode. استخدم هذا الـ tap لأنه يتلقى تحديثات بوتيرة أسرع من brew install opencode الذي يديره فريق Homebrew.
• Arch Linux: استخدم sudo pacman -S opencode للإصدار المستقر، أو حزمة opencode-bin من AUR للحصول على إصدار أحدث.
• Windows: استخدم choco install opencode أو scoop install opencode، ويمكن أيضًا استخدام npm install -g opencode-ai. ويمكن تنزيل الملف الثنائي من Releases. لا يزال دعم التثبيت باستخدام Bun على Windows قيد التطوير.

انتقل إلى مجلد مشروعك، ثم شغّل OpenCode:

cd /path/to/project
opencode

عند الاستخدام لأول مرة، يمكنك تشغيل /init. سيحلل المشروع وينشئ ملف AGENTS.md في المجلد الجذر للمشروع. ويمكن إضافة هذا الملف إلى Git حتى يحتفظ المشروع بهذه التعليمات.

الحصول على معلمات الاتصال من OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: انسخ المعرّف الكامل من قائمة النماذج الحالية في OmniProxy

يمثل baseURL عنوان الخدمة، ويمثل API Key بيانات اعتماد الوصول، أما Model ID فهو الاسم الكامل للنموذج.

عند استخدام /v1/chat/completions، يجب أن تكون حزمة npm هي @ai-sdk/openai-compatible. تمثل Chat Completions واجهة لطلبات المحادثة. لا تستخدم @ai-sdk/openai إلا إذا كان النموذج يعمل عبر /v1/responses. وعند استخدام OmniProxy عبر مسار إكمالات المحادثة، احتفظ بحزمة التوافق.

انسخ معرّف النموذج كاملًا من قائمة OmniProxy الحالية، مع الاحتفاظ بالشرطات المائلة. كان معرّفا المقارنة بتاريخ 2026-10-09 هما claude-sonnet-5-5 وgpt-6-luna. يدعم gpt-6-luna واجهة Chat Completions، ولا يدعم استدعاء الدوال ضمن Chat Completions إلا عندما تكون قيمة reasoning_effort هي none. لا تنسخ معرّفًا غير موجود في القائمة.

إدخال إعدادات الأداة

يمكن فهم Provider على أنه مجموعة الإعدادات التي يستخدمها OpenCode للاتصال بخدمة النماذج. تُعامل خدمات OpenAI المتوافقة غير الموجودة في قائمة /connect على أنها Provider مخصص. وخدمة OpenAI المتوافقة هي خدمة تستخدم تنسيق الطلبات نفسه ويمكن استدعاؤها باستخدام الفئة نفسها من برامج العميل.

1. شغّل /connect داخل OpenCode، ثم مرّر إلى Other.
2. أدخل Provider ID. سيُستخدم omniproxy أدناه. اختر معرّفًا يسهل تذكره، لأنك ستحتاج إلى استخدام المعرّف نفسه في ملف الإعدادات.
3. أدخل API Key الخاص بـ OmniProxy. تحفظ هذه الخطوة بيانات الاعتماد فقط؛ ولا يزال عليك إدخال العنوان والنماذج في opencode.json. تُحفظ بيانات الاعتماد في ~/.local/share/opencode/auth.json.
4. أنشئ ملف opencode.json في مجلد المشروع أو عدّله:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. شغّل /models، وسيظهر كل من Provider المخصص والنماذج في القائمة.

يجب أن يتطابق المعرّف المستخدم في /connect مع المفتاح الموجود في opencode.json. لا تكتب المفتاح الحقيقي في هذا الملف. إذا لم تستخدم /connect، فيمكنك أيضًا استخدام صيغة متغير البيئة داخل options.apiKey، مثل {env:اسم_المتغير}. في الاختبار بتاريخ 2026-10-09 باستخدام OpenCode 1.18.34، نجح الاتصال أيضًا عند كتابة المفتاح مباشرةً في options.apiKey الخاص بالمشروع من دون استخدام /connect. وإذا كانت البوابة لا تتحقق من المفتاح، فيمكن أن تكون هذه القيمة سلسلة أحرف نائبة لا تُستخدم إلا محليًا. يجب أن تستخدم مفاتيح models المعرّفات الكاملة الموجودة في القائمة.

المفتاح

/connect

• اختر Other في الأسفل
• عيّن Provider ID بنفسك
• يُحفظ في auth.json

المشروع

opencode.json

• يجب أن يحمل مفتاح provider الاسم نفسه
• استخدم حزمة التوافق مع npm
• اجعل baseURL ينتهي بـ /v1

الاختيار

/models

• يظهر النموذج في القائمة
• اختر واحدًا ثم اطرح سؤالك
• اعتمد ID الوارد في قائمة البوابة

التحقق باستخدام مهمة حقيقية

شغّل أولًا مهمة حقيقية من داخل مجلد المشروع. تنسيق مرجع النموذج هو Provider ID/معرّف النموذج، ويجب الاحتفاظ بأي شرطات مائلة داخل معرّف النموذج:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "اشرح وظيفة ملف أحدده لك، ولا تعدّل الملف."

يسمح الخيار --auto لهذه العملية باستخدام أدوات مثل قراءة الملفات. في الاختبار بتاريخ 2026-10-09 باستخدام OpenCode 1.18.34، تمت قراءة محتوى الملف المحدد. استغرقت المرة الأولى نحو دقيقتين.

للاستخدام التفاعلي، شغّل opencode ثم اختر النموذج باستخدام /models. ويمكن استخدام @ للبحث عن الملفات. استخدم opencode auth list للتأكد من بيانات الاعتماد المحفوظة عبر /connect، ثم تحقق من المصدر ومعرّف النموذج في سجلات الاستدعاء داخل OmniProxy.

التشغيل

يمكن تشغيل opencode

• استخدم cd للانتقال إلى المشروع أولًا
• يظهر ID في auth list
• ملف الإعداد موجود في المشروع

المهمة

قرأ الشيفرة

• اسأله عن ملف محدد
• راجع شرحه
• استخدم /undo إذا لم يكن صحيحًا

السجل

يظهر في البوابة

• المصدر هو OpenCode
• معرّف النموذج متطابق
• لا ترسل المفتاح إلى المستودع

الأخطاء الشائعة

• لا يظهر OmniProxy في /models: تحقق من تطابق معرّف /connect مع المفتاح الموجود في opencode.json، ومن أن قيمة npm هي @ai-sdk/openai-compatible، وأن baseURL ينتهي بـ /v1.
• اختفت بيانات الاعتماد: شغّل opencode auth list. لن تظهر هنا خدمات Provider التي تعتمد على متغيرات البيئة، مثل Bedrock؛ أما Provider المخصص الذي يستخدم /connect فيفترض أن يظهر.
• وظائف Windows غير مكتملة: استخدم سكربت التثبيت داخل WSL بدلًا من ذلك.
• معرّف النموذج غير صالح: انسخه مجددًا من قائمة OmniProxy الحالية، ثم عدّل المفتاح الموجود في models.
• يُرسل الطلب إلى الواجهة الخطأ: احتفظ بـ @ai-sdk/openai-compatible لإكمالات المحادثة. لا تغيّر الحزمة من أجل واجهة Responses إلا إذا كان هذا النموذج في OmniProxy يعمل فعلًا عبر /v1/responses.

المراجع الرسمية

للتثبيت، راجع مقدمة OpenCode. ولإعداد Provider مخصص، راجع Providers. أما معرّفات النماذج المستخدمة في الأمثلة، فراجع نظرة عامة على نماذج Claude وGPT-6 Luna.

استبدل كل عنصر نائب بقيم إعداد OmniProxy الخاصة بك. لا تنشر مفتاحاً حقيقياً أبداً.

لا يثبت الحفظ الناجح أو HTTP 200 وحده توافق Agent الكامل. تحقق من المصدر والنموذج في سجل استدعاءات OmniProxy.

المصادر الرسمية · OpenCode ↗