تشغيل Kimi K3.1 Pro في Claude Code وCodex: الإعدادات، والإخفاقات الصامتة، والتبديل بسطر واحد

يتحدث Kimi K3.1 Pro ثلاث بروتوكولات: OpenAI Chat Completions وOpenAI Responses وAnthropic Messages. وهذا هو السبب الكامل وراء إمكانية اندماجه في Claude Code وCodex دون وسيط ترجمة — فكل أداة تتحدث بالفعل أحد هذه الثلاثة، وMoonshot يوفّر ذلك البروتوكول أصليًا. الإعداد عبارة عن حفنة من متغيرات البيئة في حالة واحدة، وكتلة TOML من خمسة أسطر في الحالة الأخرى. أما الجزء الذي يكلّف الناس بعد ظهر كامل فليس الإعداد؛ بل نمط الفشل. يستخدم Claude Code أربعة مستويات مختلفة من النماذج لمهام مختلفة، وأي مستوى يُترك دون تعيين يفشل بصمت بدلًا من أن يفشل بوضوح.

كُتب هذا الدليل استنادًا إلى وثائق التكامل الخاصة بـ Moonshot، وتم التحقق منها في 24 أكتوبر 2026، مع التحفظات التي تخفيها الوثائق. وحيثما تختلف قيمة ما عند توجيه الأدوات نفسها إلى بوابة توجيه بدلًا من توجيهها إلى Moonshot مباشرةً، يُشار إلى ذلك صراحةً.

لماذا لا حاجة إلى وكيل

Claude Code talks to Anthropic's Messages API; Codex talks to the Responses API. Moonshot exposes both. Its Anthropic-compatible surface lives at https://api.moonshot.ai/anthropic and its Responses API at https://api.moonshot.ai/v1, and the model id is kimi-k3.1-pro on both. Nothing in either client needs to know it is not talking to the vendor it was built for.

ثمة نتيجة جديرة بالذكر قبل الإعداد: النموذج يفكّر دائمًا. لا يوجد مفتاح لتشغيل التفكير أو إيقافه، ويُضبط العمق عبر حقل من المستوى الأعلى reasoning_effort يقبل القيم low وhigh وmax، مع القيمة الافتراضية max. معاملات أخذ العينات ثابتة — temperature 1.0، top-p 0.95، n عند 1 — وتمرير قيم أخرى يعيد خطأً. إذا كان إعدادك السابق قد ضبط temperature، فإن ذلك الضبط لا يستمر بعد التبديل.

Claude Code: كتلة البيئة

يقرأ Claude Code إعداداته من env في كتلة ~/.claude/settings.json. المتغيرات المكتوبة هناك تتجاوز الأسماء نفسها المصدَّرة في صدفة الطرفية لديك، وهذا ميزة وفخّ في آنٍ واحد: التصدير القديم في طرفيتك لن ينقذك إذا قال الملف شيئًا آخر.

• ANTHROPIC_BASE_URL — the Kimi endpoint root. Set it to https://api.moonshot.ai/anthropic. If you leave it unset, requests go to Anthropic and fail authentication.

• ANTHROPIC_AUTH_TOKEN — مفتاح Kimi API الخاص بك. هذا هو المتغيّر الذي يستخدمه Claude Code فعليًا لرمز Bearer؛ أما وضع مفتاح API في ANTHROPIC_API_KEY بدلًا من ذلك، فهو السبب الأكثر شيوعًا وراء إرجاع إعداد يبدو صحيحًا لخطأ 401.

• ANTHROPIC_MODEL — نموذج المحادثة الرئيسي: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL، ANTHROPIC_DEFAULT_SONNET_MODEL، ANTHROPIC_DEFAULT_HAIKU_MODEL، ANTHROPIC_DEFAULT_FABLE_MODEL — واحد لكل فئة. عيّن الثلاثة الأولى على الأقل، ووجّه HAIKU إلى نموذج رخيص وسريع بدلًا من النموذج الرائد؛ فمثال Moonshot نفسه يربط تلك الفئة بنموذجه الخاص بالبرمجة.

• CLAUDE_CODE_SUBAGENT_MODEL — ما تستخدمه الوكلاء الفرعيون. عند عدم ضبطه، تتدهور أعمال الوكلاء الفرعيين أو تفشل.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — اضبطه على 1000000، بما يطابق نافذة السياق. القيمة الصغيرة جدًا تؤدي إلى ضغط مبكر وتجاهل للسياق؛ أما القيمة الكبيرة جدًا فتؤدي إلى أخطاء في طول السياق.

• CLAUDE_CODE_EFFORT_LEVEL — يضبط دليل Moonshot هذا على max، وهو أيضًا الإعداد الافتراضي للنموذج. يؤدي خفضه إلى تقليل الجودة في المهام المعقدة، كما أن تغييره في منتصف الجلسة يُبطل إصابات ذاكرة التخزين المؤقت للبادئة.

المستويات الأربعة التي تفشل بصمت

هذا هو الفشل الذي يستحق التخطيط له. يستخدم Claude Code نماذج مختلفة للمحادثة الرئيسية، والتلخيص في الخلفية، والوكلاء الفرعيين، واستدعاءات الأدوات المساعدة الصغيرة. إذا قمت بتهيئة ANTHROPIC_MODEL فقط، فلن تُظهر المسارات الأخرى خطأً — بل ستفعل بهدوء لا شيئًا مفيدًا، أو ستتراجع بطرق تجعل الأداة تبدو معطلة دون تسمية سبب. جدول Moonshot المرجعي صريح في أن كل طبقة غير مضبوطة تتسبب في فشل المهمة المقابلة، وتبدو الأعراض كأن الوكيل بطيء أو مرتبك بدلًا من أن تبدو كخطأ في التهيئة.

قائمة التحقق العملية هي ضبط متغيرات المستوى (tier) الأربعة كلها بالإضافة إلى متغير الوكيل الفرعي في تعديل واحد، ثم إعادة تشغيل Claude Code، ثم التأكد في إحدى الجلسات من أن الوكيل الفرعي يعمل فعليًا. وإذا تعثّر، فإن المستوى هو أول ما ينبغي فحصه، لا النموذج.

Codex: كتلة TOML واحدة

Codex reads ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml). The connection is defined by four values in a provider block: the model id kimi-k3.1-pro, a provider named kimi, base_url pointing at https://api.moonshot.ai/v1, the environment-variable name that holds the key, and — the setting that makes the direct connection work — wire_api = "responses". Set model_context_window to 1048576 as well; without it Codex falls back to default model metadata, which degrades behaviour on long inputs.

المفتاح نفسه ينتمي إلى البيئة، لا إلى الملف. يقرأه Codex من المتغير المسمى في env_key، لذا أبقِ config.toml خاليًا من الأسرار واضبط المتغير في ملف تعريف الصدفة أو بيئة النظام.

حدّان يجدر معرفتهما قبل الإبلاغ عن خطأ. لا يقبل Codex CLI الفيديو كمدخل رغم أن النموذج يقبله — فهذا قيد في طبقة الإدخال لدى Codex، لذا يجب أن يمرّ العمل على الفيديو عبر واجهة API مباشرة. كما تظل إدارة السياق الخاصة بـ Codex سارية: نافذة سعة مليون رمز لا تعني أن كل جلسة ينبغي أن تستخدمها.

توجيه كلتا الأداتين نحو بوابة واحدة بدلًا من ذلك

كل ما سبق يعمل دون تغيير إذا استبدلت عناوين URL الأساسية الخاصة بـ Moonshot بعناوين URL الأساسية لبوابة ما، وهو أمر مفيد عندما تستدعي قاعدة الشيفرة نفسها أيضًا نماذج من موردين آخرين./v1/chat/completions، /v1/responses و/v1/messages — وينشر النموذج تحت المعرّف kimi/kimi-k3.1-pro.

For Claude Code, that means ANTHROPIC_BASE_URL set to the gateway root (https://api.orcarouter.ai) with the provider-prefixed model id in the four tier variables. For Codex, the same TOML block with the base URL pointing at https://api.orcarouter.ai/v1 and the model id kimi/kimi-k3.1-pro. The key variable stays the same shape; it just holds a gateway key instead of a vendor key.

ما تحصل عليه مقابل هذا الاستبدال هو بيانات اعتماد واحدة لكل نموذج في الكتالوج، وسياسة توجيه قادرة على نقل الطلب بين المورّدين دون تغيير شيفرة التطبيق — وهو ما يجعل خطةً احتياطية ممكنة عندما تفرض نقطة وصول نموذج جديد حدودًا على معدّل الطلبات في أسبوع الإطلاق. وما تتخلى عنه هو لوحة تحكم المورّد نفسها وأي واجهات إصدار تجريبي خاصة به. تُمرَّر الأسعار وفق قائمة المزوّد: 2.00 دولار لكل مليون توكن إدخال و10.00 دولارات لكل مليون توكن إخراج لـ Kimi K3.1 Pro، دون إضافة أي هامش ربح.

التحقق في خمس دقائق

• اضرب نقطة النهاية مباشرةً قبل لمس العميل: طلب POST إلى مسار Messages أو Chat Completions بطلب من رمز واحد يجب أن يُرجع JSON، ويعني 401 أن المفتاح خاطئ أو ينتمي إلى المنصة الأخرى.

• في Claude Code، اطرح سؤالاً يُلزم استخدام وكيل فرعي — بحث عبر عدة ملفات — وراقب ما إذا كان يُكمل مهمته. فهذا أسرع اختبار لإعدادات الطبقة.

• في Codex، ابدأ جلسة على مستودع صغير وتحقق من أن النموذج يُبلغ عن نافذة 1M؛ إذا أبلغ عن قيمة افتراضية أصغر، model_context_window لم يُطبّق.

• اضبط مستوى الجهد عمدًا، مرة واحدة، في بداية الجلسة: الأقصى لتصحيح الأخطاء الشاق، والمرتفع للتعديلات العادية، والمنخفض للاستخراج والتنسيق. القيمة الافتراضية هي الأقصى، وعلى هذا الطراز يُعد ذلك الخيار المكلف.