كيفية استخدام كوديكس مع أي نموذج مفتوح المصدر (وضع OSS)

يأتي Codex مزودًا بنماذج OpenAI افتراضيًا، لكنه لا يقيدك بها. يحتوي واجهة سطر الأوامر (CLI) على وضع OSS مدمج لأوقات التشغيل المحلية مثل Ollama وLM Studio، بالإضافة إلى نظام موفر مخصص يوجه الوكيل إلى أي نقطة نهاية متوافقة تحددها في ملف TOML. هذا يعني أنه يمكنك تشغيل gpt-oss على جهاز الكمبيوتر المحمول الخاص بك، أو تشغيل Codex باستخدام DeepSeek أو Qwen API مستضاف، أو التبديل بين الموفرين لكل مشروع.

يرشدك هذا الدليل خلال الإعداد بالكامل: ما يفعله وضع OSS، ومفاتيح التكوين الدقيقة، ووصفات لكل نموذج، والمقايضات التي تقبلها عند استبدال نماذج OpenAI. كل ما هنا يأتي من وثائق تكوين Codex المتقدمة الرسمية. عندما تكون الوثائق غامضة، سأذكر ذلك بدلاً من التخمين.

ملاحظة واحدة قبل أن نبدأ. بمجرد تشغيل النموذج الخاص بك داخل Codex، يكون النموذج هو نصف سير العمل فقط. النصف الآخر هو التحقق من واجهات برمجة التطبيقات (APIs) التي يبنيها وكيلك ويستدعيها. هنا يأتي دور Apidog، وسنغطي هذا الاقتران قرب النهاية.

باختصار

وضع Codex OSS هو ميزة في واجهة سطر الأوامر (CLI). قم بتشغيل codex --oss وسيتحدث Codex إلى خادم Ollama أو LM Studio محلي بدلاً من OpenAI. قم بتعيين oss_provider = "ollama" في ~/.codex/config.toml لجعله الإعداد الافتراضي، وقم بتمرير -m <model> لاختيار النموذج المحلي الذي سيتم تشغيله. بالنسبة للنماذج مفتوحة المصدر المستضافة (DeepSeek، Qwen، GLM عبر واجهات برمجة التطبيقات الخاصة بها)، قم بتعريف كتلة [model_providers.<id>] مع base_url و env_key، ثم حددها باستخدام model_provider. الملاحظة الهامة: يشير المرجع الحالي للتكوين إلى responses كقيمة wire_api الوحيدة المدعومة، لذا يجب أن تتحدث نقطة النهاية الخاصة بك بروتوكول Responses API.

ما هو وضع OSS

وضع OSS هو اختصار Codex للتشغيل مقابل خوادم النماذج مفتوحة المصدر المحلية. تصف الوثائق موفرين محليين مدعومين:

• **Ollama**، وقت تشغيل النموذج المحلي الشهير
• **LM Studio**، تطبيق سطح المكتب مع خادم محلي مدمج

يمكنك تفعيله باستخدام العلامة --oss. من مرجع أوامر مطور Codex:

--oss: استخدم موفر نموذج محلي مفتوح المصدر. يستخدم Codex --local-provider، أو oss_provider الذي قمت بتكوينه، أو يطلب منك الاختيار بين LM Studio و Ollama.

توجد علامة مصاحبة، --local-provider، والتي تأخذ lmstudio أو ollama وتتجاوز الإعداد الافتراضي الخاص بك لتشغيل واحد. إذا لم تقم بتعيين أي علامة أو إعداد افتراضي للتكوين، فإن واجهة سطر الأوامر التفاعلية ستطالبك بالاختيار. لا يطالب codex exec غير التفاعلي؛ بل يخرج بخطأ. لذا، بالنسبة للبرامج النصية و CI، قم دائمًا بتعيين الموفر بشكل صريح.

ملاحظة صادقة حول الواجهات: تغطي الوثائق وضع OSS والموفرين المخصصين ضمن نظام config.toml لواجهة سطر الأوامر (CLI). لم يتم ذكر دعم امتداد IDE وCodex السحابي للموفرين المحليين في أي مكان في وثائق التكوين. [تحقق: ما إذا كان امتداد Codex IDE يقرأ model_providers من config.toml بنفس الطريقة التي يقرأها بها CLI؛ لا تذكر الوثائق ذلك بأي شكل من الأشكال.] تعامل مع هذا على أنه سير عمل لواجهة سطر الأوامر حتى توثق OpenAI خلاف ذلك.

لماذا تشغل نموذجًا مفتوح المصدر داخل Codex

سؤال وجيه، بما أن Codex هو وكيل OpenAI الخاص. إليك بعض الأسباب الحقيقية:

• **التحكم في التكلفة.** الاستنتاج المحلي عبر Ollama لا يكلف شيئًا لكل توكن. إذا كنت تستنزف حدود الاستخدام في جلسات الوكيل الطويلة، فإن النموذج المحلي يتعامل مع العمل الشاق بينما توفر الاستدعاءات المستضافة للمشكلات الصعبة.
• **الخصوصية والعمل بمعزل عن الشبكة.** بعض قواعد الأكواد لا يمكن أن تغادر الجهاز. يحافظ نموذج Kimi أو GLM أو gpt-oss المحلي على كل توكن على جهازك. يغطي دليلنا حول تشغيل Kimi K3 محليًا ما يتطلبه ذلك عمليًا.
• **تفضيل النموذج.** أغلقت النماذج ذات الأوزان المفتوحة معظم الفجوة في البرمجة. تتجاوز واجهات برمجة التطبيقات المستضافة لـ DeepSeek و Qwen أسعار OpenAI مع تحقيق نتائج ضمن النطاق في معايير البرمجة، وقد تعجبك ببساطة طريقة كتابة نموذج معين للتعليمات البرمجية.
• **عدة نماذج لوكيل واحد.** تجربة المستخدم (UX) الطرفية في Codex، وتقنية الساندبوكس، وسير عمل الموافقة جيدة. يتيح لك تكوين الموفر الحفاظ على هذا الإطار وتبديل العقل المدبر.

مكان وجود التكوين

يخزن Codex الحالة تحت CODEX_HOME، والذي يكون افتراضيًا ~/.codex. يكون التكوين على مستوى المستخدم الخاص بك هو ~/.codex/config.toml، ويمكن للمستودع (repo) أن يحمل تجاوزات على مستوى المشروع في .codex/config.toml. كل ما يلي يذهب في أحد هذين الملفين.

بدء سريع: Codex مع Ollama

المسار الأسرع للوصول إلى نموذج مفتوح المصدر في Codex هو Ollama.

1. قم بتثبيت Ollama من ollama.com وابدأ تشغيله. يقدم واجهة برمجة تطبيقات متوافقة مع OpenAI على المنفذ 11434.
2. اسحب نموذجًا. إصدار OpenAI الخاص ذو الأوزان المفتوحة هو الخيار الأول الطبيعي؛ تحتوي صفحة مكتبة gpt-oss على المتغيرين 20b و 120b. لقد غطينا الإعداد المستقل في كيفية تشغيل gpt-oss باستخدام Ollama.

ollama pull gpt-oss:20b

3. شغل Codex في وضع OSS وقم بتسمية النموذج:

codex --oss -m gpt-oss:20b

تتجاوز العلامة -m/--model النموذج المُكوّن، وبالاقتران مع --oss، فإنها تحدد النموذج المحلي الذي سيتم تشغيله. للاستخدام غير التفاعلي:

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

4. اجعله الإعداد الافتراضي حتى تتمكن من إسقاط العلامات. في ~/.codex/config.toml:

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

هذه هي الميزة الكاملة للنماذج المحلية. لا يوجد مفتاح API، ولا كتلة موفر مخصصة. يعمل LM Studio بنفس الطريقة: قم بتحميل نموذج في التطبيق، وابدأ تشغيل خادمه المحلي، وشغل codex --oss --local-provider lmstudio. راجع lmstudio.ai لإعداد الخادم.

الموفرون المخصصون: وجه Codex إلى أي نقطة نهاية متوافقة

يغطي وضع OSS برنامجي Ollama و LM Studio. أما بالنسبة لكل شيء آخر، مثل واجهات برمجة تطبيقات DeepSeek أو Qwen المستضافة، أو خادم وكيل، أو خادم vLLM على شبكة LAN الخاصة بك، فإن Codex لديه موفرو نماذج مخصصون. تُعرّف الوثائق الموفر بأنه "كيفية اتصال Codex بنموذج (عنوان URL الأساسي، واجهة برمجة تطبيقات الاتصال، المصادقة، ورؤوس HTTP الاختيارية)."

النمط من الوثائق الرسمية:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

المفاتيح الهامة هي:

يتوفر أيضًا ضبط الشبكة لكل موفر: request_max_retries (الافتراضي 4)، stream_max_retries (الافتراضي 5)، و stream_idle_timeout_ms (الافتراضي 300000). تستفيد الأجهزة المحلية البطيئة من مهلة خمول أطول، حيث يمكن لنموذج 120b على جهاز كمبيوتر محمول أن يظل صامتًا لفترة بين الرموز.

هناك قاعدتان تشير إليهما الوثائق مباشرة. أولاً، معرفات openai و ollama و lmstudio محجوزة؛ لا يمكنك تجاوز الموفرين المدمجين. لتغيير عنوان URL الأساسي لموفر OpenAI المدمج، قم بتعيين openai_base_url بدلاً من إنشاء [model_providers.openai]. ثانيًا، وهذه القاعدة تشكل كل شيء: مرجع التكوين ينص على أنه بالنسبة لـ wire_api، "responses هي القيمة الوحيدة المدعومة، وهي الافتراضية عند حذفها."

هذا قيد حقيقي. كانت الإصدارات السابقة من Codex تقبل wire_api = "chat" لنقاط نهاية Chat Completions، ولا تزال صفحة نظرة عامة على النماذج تقول إنه يمكنك توجيه Codex إلى الموفرين الذين يدعمون "إما Chat Completions أو Responses APIs". المرجع والنظرة العامة غير متفقين. [تحقق: ما إذا كان wire_api = "chat" لا يزال يعمل في الإصدار الحالي من CLI؛ مرجع التكوين يقول Responses فقط، وصفحة النماذج تشير إلى أن Chat لا يزال يعمل. اختبر مقابل نقطة نهاية Chat فقط قبل النشر.] إذا كان Responses فقط هو الصحيح، فإن موفرك يحتاج إلى نقطة نهاية Responses API، والتي تكشفها معظم الخوادم المتوافقة مع OpenAI الآن ولكن بعض واجهات برمجة التطبيقات المستضافة لا تزال لا تفعل ذلك.

وصفات نموذج بنموذج

كل وصفة أدناه هي عبارة عن كتلة تكوين بالإضافة إلى الأمر المراد تشغيله. قم بتعيين متغير بيئة مفتاح API قبل التشغيل.

DeepSeek (واجهة برمجة تطبيقات مستضافة)

أضافت DeepSeek دعم Responses API جنبًا إلى جنب مع إصدارها التجريبي V4 Flash، وهو بالضبط ما يتطلبه بروتوكول اتصال Codex. لقد غطينا هذا الطرح في DeepSeek V4 Flash، و Responses API، و Codex.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

تحقق من وثائق DeepSeek API لمعرفات النماذج الحالية. [تحقق: المسار الدقيق لعنوان URL الأساسي الذي توثقه DeepSeek للوصول إلى بروتوكول Responses؛ قد يختلف مسار الدردشة /v1 عن مسار Responses.]

Qwen (مستضاف عبر Model Studio)

يعرض Model Studio (DashScope) من Alibaba وضعًا متوافقًا مع OpenAI لعائلة Qwen 3.8. كانت نقطة نهاية الوضع المتوافق تاريخيًا على شكل Chat Completions. [تحقق: ما إذا كان الوضع المتوافق في DashScope يقدم الآن بروتوكول Responses؛ إذا لم يكن الأمر كذلك، فإن هذه الوصفة تعتمد على سؤال wire_api = "chat" أعلاه.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

يغطي دليل Qwen 3.8 API الخاص بنا المفاتيح، ومعرفات النماذج، والتسعير للمسار المستضاف.

Kimi، GLM، وأوزان مفتوحة أخرى (محليًا عبر Ollama)

أي شيء يمكنك سحبه إلى Ollama يعمل من خلال وضع OSS العادي، لا حاجة لكتلة موفر:

ollama pull <model>
codex --oss -m <model>

يغطي ذلك GLM وأوزان Qwen المفتوحة، بالإضافة إلى Kimi K3 إذا كان جهازك يتحملها (أوزان K3 تبلغ 594 جيجابايت في MXFP4، لذا يجب على معظم الأشخاص قراءة تشغيل Kimi K3 محليًا قبل المحاولة). بالنسبة للأجهزة متوسطة الحجم، يعتبر gpt-oss:20b أو بنية Qwen coder المُكمّاة خيارًا عمليًا.

vLLM مستضاف ذاتيًا أو خادم شبكة محلية (LAN)

يعتبر vLLM أو خادم مشابه متوافق مع OpenAI على جهاز آخر موفرًا مخصصًا، وليس وضع OSS:

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "vLLM on the workstation"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

الملفات الشخصية: تبديل العقول لكل مهمة

ليس عليك اختيار إعداد واحد. ملفات تعريف Codex هي ملفات TOML منفصلة في ~/.codex/<profile-name>.config.toml، يتم تراكبها فوق التكوين الأساسي الخاص بك عند تمرير --profile. يبدو ملف تعريف النموذج المحلي بهذا الشكل:

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"

احتفظ بتكوينك الافتراضي على نماذج OpenAI لإعادة الهيكلة الصعبة وقم بتشغيل --profile oss-local لإصلاحات lint، وإنشاء هياكل الاختبار، وتمرير الوثائق. تعمل التجاوزات لمرة واحدة بدون ملف تعريف أيضًا: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

المقايضات مقابل نماذج OpenAI

كن صريحًا مع نفسك بشأن ما تتنازل عنه:

• **القدرة.** gpt-oss:20b ليس gpt-5.6-terra. تفشل النماذج المحلية في كثير من الأحيان في التعديلات الطويلة لملفات متعددة، وتضخم حلقات الوكيل ضعف النموذج لأن كل خطوة تبنى على سابقتها.
• **السرعة.** واجهات برمجة التطبيقات المستضافة (APIs) تبث البيانات بسرعة. قد يكون النموذج المحلي الكبير على أجهزة المستهلك بطيئًا بما يكفي لتغيير طريقة عملك.
• **دقة الأدوات.** تم ضبط أوامر Codex واستدعاء الأدوات لنماذج OpenAI. تختلف النماذج مفتوحة المصدر في مدى موثوقية إصدارها لاستدعاءات الأدوات، ويضيّق بروتوكول الاتصال (responses-only wire protocol) نطاق نقاط النهاية المؤهلة على الإطلاق.
• **نطاق الدعم.** وضع OSS هو مسار موثق لواجهة سطر الأوامر (CLI)، ولكن الموفرين الخارجيين يقعون على عاتقك: معرفات النماذج، وحدود المعدل، وغرائب البروتوكول هي بينك وبين البائع.

التقسيم العملي: نماذج محلية أو مستضافة رخيصة للعمل عالي الحجم ومنخفض المخاطر، ونماذج متطورة للمهام التي يكلفك فيها تشغيل فاشل فترة بعد الظهر.

تحقق من واجهات برمجة التطبيقات التي يتعامل معها وكيلك

بغض النظر عن النموذج الذي يعمل داخل Codex، يكون الناتج عادةً رمزًا يستدعي أو يحدد واجهات برمجة التطبيقات، وتتخيل النماذج مفتوحة المصدر نقاط نهاية ومخططات أكثر تكرارًا من النماذج المتطورة. اكتشف ذلك في طبقة API بدلاً من الإنتاج.

يغطي Apidog هذا الجانب من سير العمل. وجّه خادم Apidog MCP إلى مشروعك ويمكن لوكيل Codex قراءة مواصفات API الحقيقية أثناء كتابته للرمز، بدلاً من اختراع أسماء الحقول. ثم استخدم واجهة سطر الأوامر (CLI) الخاصة بـ Apidog داخل Codex للسماح للوكيل بتشغيل سيناريوهات الاختبار الخاصة بك من الطرفية بعد كل تغيير: يقوم بالتحرير، ويقوم بالاختبار، وتقوم أنت بمراجعة التغيير الناجح. هذه الحلقة تهم أكثر، لا أقل، عندما يكتب نموذج أصغر الرمز. قم بتنزيل Apidog لربطه؛ تعمل واجهة سطر الأوامر وخادم MCP مع أي نموذج قمت بتكوينه.

استكشاف الأخطاء وإصلاحها

• **codex exec يظهر أخطاء فورًا في وضع OSS.** لم تقم بتعيين موفر. التشغيلات غير التفاعلية لا تطلب منك اختيارًا أبدًا، لذا قم بتمرير --local-provider ollama أو قم بتعيين oss_provider في التكوين.
• **رفض الاتصال على المنفذ 11434.** Ollama لا يعمل، أو أنه مرتبط بعنوان مختلف. ابدأ التطبيق أو ollama serve، وتأكد باستخدام curl http://localhost:11434/v1/models.
• **أخطاء 404 أو أخطاء بروتوكول من موفر مستضاف.** شكل base_url خاطئ، أو أن نقطة النهاية لا تتحدث بروتوكول Responses. تحقق مما إذا كان البائع يوثق مسارًا متوافقًا مع Responses.
• **فشل المصادقة.** env_key يسمي متغير بيئة؛ يقرأ Codex المفتاح من بيئة shell الخاصة بك عند التشغيل. قم بتصديره في نفس shell، وتذكر أن launchd أو CI shells قد لا تقوم بتحميل ملفات الإعداد الخاصة بك (dotfiles).
• **تتوقف التدفقات (Streams) في منتصف التوليد على نموذج محلي بطيء.** ارفع قيمتي stream_idle_timeout_ms و stream_max_retries في كتلة الموفر.
• **تجاهل تعديلات التكوين.** تحقق من وجود ملف .codex/config.toml على مستوى المشروع يتجاوز تكوين المستخدم الخاص بك، وتذكر أن ملفات التعريف تتراكب فوق كليهما.

الأسئلة الشائعة

هل يعمل وضع Codex OSS في امتداد IDE أو سحابة Codex؟

توثق المستندات وضع OSS والموفرين المخصصين كجزء من نظام التكوين الخاص بواجهة سطر الأوامر (CLI). دعم IDE أو السحابة للموفرين المحليين غير موثق، لذا تعامل مع هذا على أنه ميزة خاصة بواجهة سطر الأوامر. [تحقق قبل الاعتماد على دعم IDE.]

ما هي النماذج التي تعمل بشكل أفضل مع Codex في وضع OSS؟

أي شيء يمكن أن يقدمه Ollama أو LM Studio على جهازك. gpt-oss:20b هو الافتراضي قليل الاحتكاك. تشمل خيارات البرمجة القوية ذات الأوزان المفتوحة عائلة Qwen 3.8 و GLM؛ بالنسبة للنماذج العملاقة مثل Kimi K3، تحقق من متطلبات الأجهزة في دليل Kimi K3 المحلي الخاص بنا أولاً.

هل يمكنني استخدام OpenRouter أو مجمع آخر مع Codex؟

أي مجمع (aggregator) يكشف نقطة نهاية متوافقة يتناسب مع نمط [model_providers.<id>]: قم بتعيين base_url و env_key، ثم حدده باستخدام model_provider. السؤال المفتوح هو البروتوكول: يشير مرجع التكوين إلى responses كقيمة wire_api الوحيدة المدعومة، لذا تأكد من أن المجمع الخاص بك يقدم Responses API.

هل أحتاج إلى مفتاح OpenAI API لتشغيل Codex بنموذج مفتوح المصدر؟

لا يلزم مفتاح لوضع OSS مع خادم Ollama أو LM Studio محلي. يستخدم الموفرون المستضافون المخصصون مفتاحهم الخاص عبر env_key. لا يزال يتعين عليك تسجيل الدخول إلى Codex نفسه كالمعتاد لأي شيء يتعلق بخدمات OpenAI.

قم بتشغيل الإعداد الذي يناسب المهمة. gpt-oss محلي للحلقات الرخيصة، DeepSeek أو Qwen عندما تريد سرعة مستضافة بتكلفة أقل، ونماذج OpenAI المتطورة عندما تكون المشكلة صعبة. يجعل تكوين Codex كل هذه الخيارات مجرد علامة واحدة تفصل بينها، ومع تولي Apidog التحقق من جانب API، يصبح النموذج جزءًا قابلاً للتبديل بدلاً من التزام.