المتغيرات البيئية: لوحة "المفاتيح الرئيسية" الخفية
📚 دليل السلسلة: الدرس السابق 41 المهام المتوازية علمك كيفية تقسيم المهام وتشغيل عدة نسخ من Claude معاً. هذا الدرس يغوص تحت السطح — حيث نعتمد على المتغيرات البيئية للتحكم في كيفية اتصال Claude Code بالنماذج، وتحديد وقت مهلة الاتصال، وإرسال البيانات من عدمه. هذه المفاتيح لا توجد في القوائم العادية، بل تختبئ داخل shell وملف
settings.jsonالخاص بك، وسنتعرف عليها ونضبطها اليوم.
يقال دائماً إن المتغيرات البيئية هي "أمر يخص المحترفين فقط"، وبصراحة — هذه العبارة قد ضللت الكثيرين.
فالكثير من المستخدمين يقومون بتهيئة النماذج، وضبط الوكيل (proxy)، وتعديل مهلة الاتصال يدوياً في كل مرة يفتحون فيها محادثة عبر كتابة /model وضبط الإعدادات، ليعيدوا نفس الخطوات عند فتح محادثة جديدة. وعند سؤالهم عن سبب عدم تثبيت الإعدادات، تكون الإجابة غالباً "تبدو المتغيرات البيئية أمراً معقداً ونخشى تخريب شيء".
ولكن إذا نظرت إلى الدروس الواحد والأربعين السابقة — ستجد تهيئة مفتاح API في الدرس 04، وربط النماذج المحلية في الدرس 05، وإدارة السياق في الدرس 19، وإيقاف القياس عن بعد (telemetry) في الدرس 21... تعتمد كل هذه الأمور في خلفيتها على نفس الآلية الأساسية: المتغيرات البيئية. وأنت تستخدمها بالفعل، ولكن لم يقم أحد بجمعها وشرحها معاً.
ببساطة: المتغيرات البيئية ليست حكراً على المحترفين، بل هي لوحة "المفاتيح الرئيسية" التي تضبطها مرة واحدة لتستفيد منها دائماً. والخوف منها ناتج عن عدم معرفة المفاتيح الشائعة وما قد يحدث عند الخطأ في ضبطها. وسنكشف هذا الغموض اليوم.
بعد قراءة هذا الدرس، ستحصل على:
- شرح مبسط لدور المتغيرات البيئية في Claude Code، ولماذا تستحق منك عشر دقائق لفهمها
- المقارنة بين الطرق الثلاث لضبطها (مؤقتاً في shell / بشكل دائم في ملف تهيئة shell / عبر حقل
envفي ملفsettings.json) ومتى تستخدم كل منها في جدول واحد - دور الملفات الأربعة لـ
settings.jsonفي تحديد نطاق عمل المتغير، وأيها يرفع لـ git وأيها لا يرفع — امتداداً للدرس 31 - قائمة بـ "أهم المتغيرات البيئية التي يجب معرفتها": الاتصال، مهلة الاتصال، الخصوصية، ومجلد الإعدادات، مع القيم الافتراضية وتنبيهات الأخطاء
- عند إمكانية ضبط نفس الأمر عبر متغير بيئي وحقل إعدادات معاً، فمن له الكلمة العليا (قواعد الأولويات)
- تطبيق عملي مع خطوات تشغيل ونتائج متوقعة: ضبط متغير بيئي والتحقق من عمله وتأثيره بنفسك
01 افهم أولاً: ما الذي تديره المتغيرات البيئية في Claude Code
الخلاصة أولاً: المتغيرات البيئية هي عبارة عن "مفاتيح قيم ومفاتيح" يقرأها Claude Code عند التشغيل لتحديد سلوكه الأساسي مثل كيفية الاتصال بالنموذج، والتوثيق، ومهلة الاتصال، وإرسال بيانات التشغيل.
فمعظم الميزات التي تستخدمها — مثل تبديل النموذج عبر /model، أو إضافة خدمات عبر claude mcp add، أو تعديل الإعدادات عبر /config — هي بمثابة "تعديلات مؤقتة أثناء المحادثة". ولكن هناك سلوكيات تريد تطبيقها في كل مرة تشغل فيها الكود دون الحاجة لضبطها يدوياً: مثل "الاتصال دائماً بعنوان الوكيل المخصص" أو "زيادة مهلة الطلبات إلى 20 دقيقة" أو "منع هذه الآلة من إرسال أي بيانات للقياس عن بعد". هذه القواعد الأساسية الثابتة هي ما تديره المتغيرات البيئية.
وتعبر العبارة الرسمية عن هذا الدور بدقة:
يمكن للمتغيرات البيئية التحكم في سلوك Claude Code، مثل اختيار النموذج، والمصادقة، وتوجيه الطلبات، وتبديل الميزات.
تشبيه: أزرار التحضير المسبق في آلة القهوة. في آلة قهوة توفر إعدادات مسبقة، يمكنك ضبط كل شيء يدوياً في كل مرة — كمية الماء، ودرجة التركيز، وإضافة الحليب من عدمه، لتقوم بذلك مع كل كوب؛ ويمكنك أيضاً حفظ كوبك المفضل كـ "إعداد مسبق"، لتضغط على زر واحد لاحقاً وتقوم الآلة بتحضيره بناءً على المعاملات المحفوظة. وتعمل المتغيرات البيئية بنفس الطريقة: فهي تقوم بتثبيت الإعدادات التي تريد تطبيقها دائماً، ليقرأها Claude Code فور تشغيله ويوفر عليك تكرار ضبطها.
وفي السيناريوهات الحقيقية، ستحتاج للمتغيرات البيئية في الحالات التالية غالباً:
- "قمت بربط DeepSeek، ولا أريد اختيار النموذج يدوياً في كل مرة" — كتابة النموذج والعنوان داخل المتغيرات البيئية (وهذا هو الأساس الذي اعتمد عليه الدرس 05)
- "شبكة الشركة بطيئة، ومهلة الاتصال الافتراضية المحددة بـ 10 دقائق لا تكفي" — زيادة المهلة عبر متغير واحد
- "هذه الآلة تابعة للشركة، وتتطلب معايير الامتثال إيقاف إرسال بيانات القياس عن بعد" — إيقافها بمتغير واحد (كما أشرنا في الدرس 21)
- "أملك حسابين للعمل وللاستخدام الشخصي، وأريد الفصل بينهما تماماً" — تبديل مجلد الإعدادات عبر متغير واحد
هل لاحظت؟ كل هذه متطلبات من فئة "اضبطها مرة واحدة لتستمر طويلاً". وهذا هو السبب الأساسي لوجود المتغيرات البيئية.
💡 خلاصة القول في جملة واحدة: المتغيرات البيئية هي مجموعة من مفاتيح التشغيل يقرأها Claude Code عند بدء التشغيل لإدارة سلوكياته الأساسية مثل الاتصال والتوثيق والمهلة والخصوصية؛ وتكمن قيمتها في تثبيت الإعدادات المفضلة لتعمل دائماً دون حاجة لضبطها في كل مرة.
02 أين تضبطها: ثلاث طرق، من "لهذه المرة فقط" إلى "دائماً وأبداً"
بعد معرفة دورها، يأتي السؤال العملي الأهم — أين نقوم بضبطها؟ تتوفر ثلاثة أماكن، ويكمن الفارق بينها في سؤال واحد: التعديل الذي أجريه الآن، كم يستمر من الوقت وعلى من يؤثر.
وتوضح الوثائق الرسمية هذا الفارق ببساطة:
المتغيرات المحددة داخل shell تظل فعالة طوال فترة جلسة الطرفية فقط، بينما المتغيرات المحددة في ملفات الإعدادات تطبق في كل مرة تشغل فيها
claude.
سأرتب الطرق الثلاث بحسب "اتساع نطاق التأثير من الضيق إلى الواسع" لتختار منها المناسب:
الطريقة الأولى: الضبط المؤقت داخل shell (للطرفية الحالية فقط)
قم بكتابة أمر export في الطرفية قبل تشغيل claude. ويقتصر تأثيره على نافذة الطرفية الحالية فقط، ويختفي بمجرد إغلاقها.
أنظمة macOS / Linux / WSL:
export API_TIMEOUT_MS="1200000"
claudeنظام Windows PowerShell:
$env:API_TIMEOUT_MS = "1200000"
claudeوهذه الطريقة مناسبة لـ "التجربة لمرة واحدة فقط" — مثل تجربة زيادة المهلة مؤقتاً، أو تجربة عنوان اتصال مخصص، ليختفي التعديل بمجرد إغلاق الطرفية دون ترك أي أثر.
الطريقة الثانية: الكتابة في ملف تهيئة shell (ليعمل دائماً على هذه الآلة)
إذا كنت تريد تحميل الإعداد تلقائياً مع فتح كل طرفية، فأضف سطر export لملف تهيئة shell الخاص بك. ويكون الملف الافتراضي في نظام Mac هو ~/.zshrc، وفي أنظمة Linux هو ~/.bashrc:
# أضفه في نهاية ملف ~/.zshrc
export API_TIMEOUT_MS="1200000"ويعمل الإعداد فور حفظ الملف وفتح طرفية جديدة (أو تشغيل source ~/.zshrc). ويعتبر هذا الأسلوب مناسباً لـ "تطبيق هذا الإعداد على كل المشاريع والطرفيات في جهازي الشخصي".
ولتثبيت الإعداد في نظام Windows، استخدم الأمر
setx API_TIMEOUT_MS "1200000"(في CMD) أو الأمر[Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User")(في PowerShell)، ثم افتح طرفية جديدة ليعمل الإعداد.
الطريقة الثالثة: الكتابة في حقل env داخل ملف settings.json (مرتبط بالإعدادات بغض النظر عن طريقة التشغيل)
الطريقة الثالثة وهي الأكثر استخداماً — كتابتها داخل الحقل env في ملف settings.json. وتوضح الوثائق الرسمية ميزة هذه الطريقة:
يقرأ Claude Code هذه المتغيرات مباشرة من الملف عند التشغيل، لذا ستعمل بغض النظر عن كيفية تشغيلك للأمر
claude.
{
"env": {
"API_TIMEOUT_MS": "1200000",
"BASH_DEFAULT_TIMEOUT_MS": "300000"
}
}لقد مهدنا لمسار هذا الملف وطريقة كتابته في الدرس 31 عند شرح
settings.json. ويكفي تذكر: أن الحقلenvمخصص للمتغيرات البيئية، وكتابة المتغيرات هنا يضمن قراءتها بغض النظر عن طريقة تشغيلك للأمرclaude.
قارن بين الطرق الثلاث لتحديد الخيار المناسب لعملك:
| طريقة الضبط | نطاق التأثير | هل يظل بعد إغلاق الطرفية؟ | الأنسب لـ |
|---|---|---|---|
أمر export مؤقت في shell | الطرفية الحالية فقط | ❌ يختفي | "التجربة لمرة واحدة فقط" |
ملف تهيئة ~/.zshrc وغيره | جميع طرفيات هذا الجهاز | ✅ يظل | "تطبيق الإعداد عالمياً على جهازي الشخصي" |
حقل env في settings.json | بحسب نطاق تأثير ملف الإعدادات | ✅ يظل | "الارتباط بالمشروع/الفريق ليعمل مع أي تشغيل" |
نصيحة عملية: لاختبار متغير ومعرفة مدى فائدته استخدم export المؤقت؛ وإذا قررت اعتماده لفترة طويلة فانقله لحقل env في ملف settings.json. ولماذا نفضل settings.json على ~/.zshrc؟ لأن جدول "تصنيف الملفات" في القسم التالي يوضح كيف يتيح لك settings.json تحديد نطاق المتغير بدقة "ليعمل لحسابي فقط، أو للمشروع بالكامل، أو للفريق"، وهو ما لا توفره تهيئة ~/.zshrc.
💡 خلاصة القول في جملة واحدة: تتوزع طرق الضبط الثلاث بحسب نطاق التأثير — أمر
exportمؤقت في shell (لمرة واحدة)، والتهيئة في~/.zshrc(للجهاز بالكامل)، والحقلenvفيsettings.json(مرتبط بالإعدادات ويعمل دائماً)؛ وجرب بالمرتبة الأولى، وثبت بالمرتية الثالثة كعادة مستحسنة.
03 الأنواع الأربعة لملف settings.json: من يتأثر بها وأيها يرفع لـ git
أشرنا في القسم السابق إلى أن حقل env في ملف settings.json هو المكان المفضل لضبط المتغيرات، ولكن هناك فخ حتمي للمبتدئين: فملف settings.json ليس ملفاً واحداً بل يتكون من أربعة أنواع، وكتابة المتغير في ملف معين يغير تماماً "من" يتأثر به.
لقد فصلنا هذا الأمر في الدرس 31، وسنعيد التأكيد عليه هنا من منظور المتغيرات البيئية — لأن عواقب وضع الإعداد في الملف الخاطئ حقيقية وملموسة: فقد تكتب عنوان وكيل الاتصال الخاص بك ظناً منك أنه لك وحدك، ليرتفع بالخطأ إلى git وينحرف إعداد الفريق بالكامل بسببك.
تشبيه: لوحة الإعلانات العامة بالشركة مقابل المذكرة اللاصقة على مكتبك. عندما تطبع الإدارة تنبيهاً "الحد الأقصى لتعويض المواصلات هو 50" وتعلقه على لوحة الإعلانات، فهذا تنبيه يلتزم به الجميع وتعتبر قاعدة عامة؛ أما عندما تكتب على ورقة لاصقة على مكتبك "لن أطلب تعويضاً عن القهوة هذا الشهر"، فهذه ملاحظة شخصية تخصك وحدك. وكتابة المتغير البيئي في ملف معين تشبه اختيارك بين "لوحة الإعلانات" أو "الورقة اللاصقة".
توضح اللوحة الرسمية من يتأثر بكل نوع من الملفات:
| الملف | ينطبق على |
|---|---|
~/.claude/settings.json | أنت، في جميع مشاريعك |
.claude/settings.json | كل من يعمل في هذا المشروع، ويرفع لنظام التحكم في الإصدار (git) |
.claude/settings.local.json | أنت، في هذا المشروع فقط، ولا يرفع لـ git |
| الإعدادات المدارة (Hosted settings) | كل شخص في المنظمة، ويتم نشرها بواسطة المدير |
وبالمصطلحات البسيطة، احفظ هذه القواعد الأربعة:
~/.claude/settings.json(في مجلد المستخدم الرئيسي) — "لي شخصياً، وفي جميع مشاريعي". ضع إعداداتك المفضلة هنا..claude/settings.json(في جذر المشروع) — "لكل من يعمل في هذا المشروع"، ويرفع لـ git لتتم مشاركته مع الفريق. ضع القواعد المشتركة هنا..claude/settings.local.json(في جذر المشروع) — "لي شخصياً، وفي هذا المشروع فقط"، ولا يرفع لـ git (حيث يتم تجاهل اللاحقة.localافتراضياً). ضع الإعدادات المؤقتة والبيانات الحساسة هنا.- الإعدادات المدارة — يتم إرسالها من قبل المدير للمنظمة بالكامل، ولا تملك صلاحية تعديلها أو إعدادها عادة.
وهناك خطأ يسهل الوقوع فيه هنا. ففي سبيل السرعة عند ربط بوابة اتصال خاصة، قد تكتب ANTHROPIC_BASE_URL مع عنوان يحتوي على token شخصي داخل ملف .claude/settings.json في جذر المشروع، ثم تقوم بعمل git commit دون مراجعة — فإذا لم تراجع الفروق (diff) قبل الرفع، ستواجه مشكلة حقيقية: فقد قمت بنشر عنوانك الخاص (والذي قد يحتوي على بيانات دخولك) لكل من يستطيع رؤية هذا المستودع. لذلك احفظ هذه القاعدة الذهبية: أي متغير يحتوي على طابع "شخصي خاص" (مثل عناوين الاتصال الخاصة، أو مجلد الإعدادات الشخصي)، يجب كتابته دائماً في ملف .local الذي لا يرفع لـ git؛ وضع في ملف .claude/settings.json القواعد التي يجب أن يتشاركها الفريق بأكمله فقط.
| طبيعة المتغير | الملف المناسب للكتابة فيه |
|---|---|
| تفضيل شخصي يعمل في كل المشاريع | ~/.claude/settings.json (في مجلد المستخدم الرئيسي) |
| قاعدة مشتركة للفريق ترفع مع المشروع | .claude/settings.json (يرفع لـ git) |
| إعداد شخصي يحتوي على بيانات دخول وخاص بهذا المشروع فقط | .claude/settings.local.json (❌ لا يرفع لـ git) |
💡 خلاصة القول في جملة واحدة: ينقسم ملف
settings.jsonإلى أربعة أنواع تحدد من يتأثر بالمتغير — ملف مجلد المستخدم يخصك عالمياً، وملف جذر المشروع يرفع لـ git ليتأثر به الفريق، وملف.localيخصك وحدك ولا يرفع لـ git؛ وتجنب وضع المتغيرات الحساسة في الملفات المخصصة للرفع تماماً.
04 أهم المتغيرات البيئية التي يجب معرفتها: الاتصال، المهلة، الخصوصية، والمجلد
قائمة المتغيرات البيئية الرسمية طويلة ومخيفة — فهي تحتوي على المئات من المتغيرات بدءاً من AWS Bedrock وحتى مصدري OpenTelemetry، ولن تحتاج لمعظمها طوال حياتك. لذا لن أسرد القائمة كاملة، بل سأختار أهم عشرة متغيرات قد تواجهها بالفعل، مقسمة إلى أربع فئات مع توضيح وظيفة كل منها وقيمته الافتراضية ومتى تحتاجه.
الفئة الأولى: الاتصال والمصادقة (كيفية الوصول للنموذج)
تعتبر هذه الفئة هي الأساس للدرسين 04 و 05. وتشمل ثلاثة متغيرات أساسية:
ANTHROPIC_API_KEY # مفتاح API الخاص بك
ANTHROPIC_BASE_URL # توجيه الطلبات لعنوان وكيل أو بوابة مخصصة
ANTHROPIC_MODEL # النموذج الافتراضي المستخدمANTHROPIC_API_KEY— مفتاح API الخاص بك. وتوضح الوثائق الرسمية نقطة مهمة جداً: بمجرد ضبط هذا المفتاح، سيتم استخدامه واحتساب الرصيد منه حتى لو كنت قد سجلت الدخول باشتراك مدفوع (Pro / Max...). وإذا أردت العودة لاستهلاك الاشتراك، فيجب عليك إزالة المتغير عبر تشغيلunset ANTHROPIC_API_KEY. تنبيه: في الوضع التفاعلي، سيعرض لك Claude Code تنبيهاً لتأكيد استخدام المفتاح أو رفضه مع إمكانية حفظ الاختيار للمستقبل؛ بينما في الوضع غير التفاعلي (-p) سيتم استخدام المفتاح مباشرة دون عرض تنبيه. وهو فخ يسهل الوقوع فيه — فقد تتفاجأ باحتساب الرصيد من مفتاح API بالرغم من امتلاكك اشتراك Max، لتكتشف لاحقاً وجود سطرexport ANTHROPIC_API_KEYمنسي في ملف~/.zshrc(راجع الدرس 04 لتفاصيل الاختيار بين الاشتراك ومفتاح API).ANTHROPIC_BASE_URL— توجيه طلبات API لعنوان وكيل أو بوابة مخصصة. وهو المتغير الأساسي المستخدم لربط النماذج المحلية والوسيطة (وقد كان بطل التكوينات في الدرس 05).ANTHROPIC_MODEL— تحديد النموذج الافتراضي. وتذكر قواعد الأولويات: أن معامل--modelوأمر/modelفي المحادثة يتفوقان عليه دائماً (سنفصل ذلك في القسم التالي).
الفئة الثانية: مهلة الاتصال (تعدل لتجنب انقطاع الاتصال السريع)
عند التعامل مع شبكات بطيئة أو استخدام وكلاء بعيدين، فإن تعديل مهلة الاتصال هو الحل الأنسب. ويبرز متغيران هنا:
| المتغير | وظيفته | القيمة الافتراضية |
|---|---|---|
API_TIMEOUT_MS | مهلة طلب API الفردي | 600000 (10 دقائق) |
BASH_DEFAULT_TIMEOUT_MS | المهلة الافتراضية لتشغيل أوامر bash الطويلة | 120000 (دقيقتان) |
API_TIMEOUT_MS— تحديد مهلة طلبات API بالملي ثانية. وتوضح التنبيهات الرسمية: وجوب زيادتها عند بطء الشبكة أو استخدام وكيل اتصال. ولكن لا تبالغ في الرقم — فالحد الأقصى المسموح به هو2147483647، وتجاوز هذا الرقم يسبب فيضاناً في المؤقت الداخلي ويجعل الطلبات تفشل فوراً (وهو خطأ شائع عند كتابة صفر إضافي بالخطأ، لتفشل الطلبات في نفس اللحظة وتغرق في البحث عن السبب لتكتشف لاحقاً أنه تجاوز الحد الأقصى).BASH_DEFAULT_TIMEOUT_MS— الوقت المسموح به لـ Claude لتشغيل الأوامر الطويلة (مثل تثبيت الاعتماديات أو عمليات البناء). القيمة الافتراضية هي دقيقتان، ويمكنك زيادتها عند تشغيل عمليات بناء ضخمة تستغرق وقتاً أطول.
الفئة الثالثة: الخصوصية والقياس عن بعد (للبيئات الصارمة أمنياً)
المتغيرات التي أشرنا إليها في الدرس 21 لإدارة "إرسال البيانات للخارج":
DISABLE_TELEMETRY=1 # إيقاف إرسال بيانات القياس عن بعد
DO_NOT_TRACK=1 # نفس الوظيفة، وهو اتفاق عام بين الأدوات البرمجيةDISABLE_TELEMETRY— ضبط القيمة على1لإيقاف القياس عن بعد. وتوضح الوثائق الرسمية أن بيانات القياس عن بعد لا تحتوي على أكوادك أو مسارات ملفاتك أو أوامر bash التي تشغلها؛ ولكن في البيئات الصارمة أمنياً، يفضل ضبط هذا المتغير لضمان الخصوصية التامة.DO_NOT_TRACK— ضبط القيمة على1يكافئ ضبطDISABLE_TELEMETRY. وهو اتفاق يلتزم به الكثير من مطوري أدوات CLI، وضبطه مرة واحدة يضمن تطبيقه على أدوات متعددة تتعرف عليه.
وهناك متغير يغلق كل شيء بضغطة واحدة — وهو
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1، وتوضح الوثائق الرسمية أنه يكافئ ضبط المتغيرات التالية معاً:DISABLE_AUTOUPDATERوDISABLE_FEEDBACK_COMMANDوDISABLE_ERROR_REPORTINGوDISABLE_TELEMETRY. وهو مناسب للبيئات المعزولة تماماً لغلق جميع الاتصالات غير الضرورية بمتغير واحد.
الفئة الرابعة: الحسابات المتعددة والسياق (للاستخدام المتقدم والمفيد)
متغيران مفيدان ننصح بالتعرف عليهما:
CLAUDE_CONFIG_DIR— تغيير مجلد الإعدادات الافتراضي (وهو~/.claudeافتراضياً). وتحفظ جميع الإعدادات والشهادات وتاريخ المحادثات والمكونات الإضافية داخله. والفائدة الأكبر له تكمن في تشغيل حسابات متعددة معاً — كما يوضح المثال الرسمي العملي:bash# إنشاء مجلد إعدادات مستقل لحساب العمل لتجنب التداخل alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'ويمكنك الفصل بين حساب العمل والحساب الشخصي كالتالي: تشغيل
claudeالعادي يوجهك للإعدادات الشخصية، وتشغيلclaude-workيوجهك لإعدادات مستقلة تماماً ومسجلة بحساب العمل، لتنفصل ملفات التاريخ والشهادات وتكوينات MCP بين الحسابين تماماً.DISABLE_AUTO_COMPACT— ضبط القيمة على1لإيقاف "الضغط التلقائي عند الاقتراب من الحد الأقصى للسياق" (وقد شرحنا آلية auto-compact في الدرس 19). ويظل أمر الضغط اليدوي/compactمتاحاً للاستخدام. وتحتاجه فقط إذا كنت تريد التحكم الكامل في موعد ضغط المحادثة بنفسك — ويفضل ترك الإعداد الافتراضي لمعظم المستخدمين.
⚠️ تنبيه مهم جداً: توضح الوثائق الرسمية صراحة — أن Claude Code لا يقرأ المتغيرات البيئية إلا عند "بدء التشغيل". ولذلك بعد تعديل أي متغير (سواء في shell أو في ملف
settings.json)، يجب عليك إغلاقclaudeوإعادة تشغيله ليعمل بالقيم الجديدة. وعدم استجابة التعديل يرجع في أغلب الحالات لنسيان إعادة التشغيل.
💡 خلاصة القول في جملة واحدة: تتركز المتغيرات الأكثر استخداماً في أربع فئات — الاتصال والمصادقة (
ANTHROPIC_API_KEY/BASE_URL/MODEL)، والمهلة (API_TIMEOUT_MSبـ 10 دقائق افتراضياً)، والخصوصية (DISABLE_TELEMETRY/DO_NOT_TRACK)، ومجلد الإعدادات المخصص (CLAUDE_CONFIG_DIR)؛ وتذكر دائماً إعادة تشغيلclaudeلتفعيل أي تعديل.
05 الأولويات: عند إمكانية الضبط في عدة أماكن، من يملك الكلمة العليا
بعد دراسة المتغيرات، قد يتبادر لذهنك سؤال طبيعي: يمكن تحديد النموذج عبر متغير ANTHROPIC_MODEL وعبر اختيار أمر /model في المحادثة وعبر حقل model في ملف settings.json — فإذا قمت بضبطها في الأماكن الثلاثة معاً، فمن يملك الكلمة العليا؟
هذا ما توضحه قواعد "الأولويات (precedence)". ودون فهمها، قد تواجه مشكلة غريبة مثل "لقد قمت بضبط المتغير ولكن الإعداد لم يتغير".
احفظ القاعدة العامة الأولى الواردة في الوثائق الرسمية — المتغيرات البيئية تتفوق على حقول الإعدادات:
عند وجود سلوك يمكن ضبطه عبر متغير بيئي وعبر حقل إعدادات معاً، فإن المتغير البيئي يملك الأولوية. على سبيل المثال، يتفوق
ANTHROPIC_MODELعلى حقلmodelفي الإعدادات. وعند غياب المتغير البيئي، يتم تطبيق حقل الإعدادات.
تشبيه: توجيه المدير المباشر يتفوق على كتيب الموظف. يذكر كتيب الموظف (حقل ملف settings.json) بوضوح أن "الحد الأقصى لتعويض المواصلات هو 50"؛ ولكن المدير يخبرك اليوم وجهاً لوجه "هذه الرحلة بعيدة، وسنقوم بالتعويض الكامل للمواصلات" (المتغير البيئي) — وبالتأكيد ستتبع كلام المدير في هذه الرحلة. ويعتبر المتغير البيئي بمثابة هذا "التوجيه المباشر"، وله الأولوية دائماً على الكتيب المكتوب. وعند غياب التوجيه المباشر (عدم ضبط المتغير البيئي)، تعود للالتزام بالكتيب (حقول الإعدادات).
ولكن هناك استثناء يبدو عكسياً، ويقع فيه المبتدئون غالباً: فليست كل المتغيرات البيئية تملك الكلمة العليا دائماً. وقد ذكرت الوثائق الرسمية استثناءً صريحاً للنموذج:
يتفوق معامل
--modelوأمر/modelعلى المتغيرANTHROPIC_MODEL.
وهذا يعني أن ترتيب أولويات النموذج يسير كالتالي:
أمر /model أو معامل --model ← الأولوية القصوى (اختيارك الفوري المباشر)
↓ يتفوق على
المتغير البيئي ANTHROPIC_MODEL ← الأولوية المتوسطة
↓ يتفوق على
حقل model في ملف settings.json ← الأولوية الأخيرة (الخيار الاحتياطي)لماذا ينعكس الترتيب في حالة النموذج؟ هذا أمر منطقي تماماً — فكتابة أمر /model أثناء المحادثة يعبر عن "رغبتك المباشرة في استخدام هذا النموذج حالياً"، ويجب أن تتفوق الرغبة المباشرة على المتغير البيئي المكتوب مسبقاً. وهذا يتماشى مع منطق "توجيه المدير المباشر": فالطلب الأكثر وضوحاً وحضوراً يملك الأولوية القصوى.
| طريقة التهيئة | الأولوية النسبية | الخلاصة في جملة |
|---|---|---|
أمر /model / معامل --model | القصوى | اختيارك الصريح والواضح أثناء المحادثة أو بدء التشغيل |
المتغير البيئي ANTHROPIC_MODEL | المتوسطة | الخيار الافتراضي المثبت مسبقاً |
حقل model في settings.json | الأخيرة | الخيار الاحتياطي عند غياب الأساليب السابقة |
تنبيه: قاعدة "تفوق الأوامر والمعاملات على المتغيرات البيئية" تخص إعدادات النموذج بشكل خاص وليست قاعدة عامة لكل الميزات. وتشير الوثائق الرسمية إلى أن طريقة التفاعل تختلف بحسب الميزة — فعلى سبيل المثال، يتفوق المتغير
CLAUDE_CODE_EFFORT_LEVELعلى أمر/effortفي المحادثة. ولذلك عند الشك في متغير معين، ارجع لجدول المتغيرات الرسمي لمراجعة التوضيح الخاص به، ولا تعتمد على التخمين.
وهذا الفخ قد يواجهك لمرة واحدة: تكتب نموذجاً ثابتاً في ملف settings.json عبر ANTHROPIC_MODEL لتتفاجأ في محادثة ما بتغييره عبر أمر /model ثم تنسى التغيير — لتستمر المحادثة بالعمل بالنموذج المؤقت الجديد وتتساءل عن سبب مخالفته للإعدادات الثابتة. والسبب واضح وبسيط: أمر /model المباشر يتفوق على المتغير البيئي المثبت. وهذا سلوك مقصود وليس خطأ برمجياً.
💡 خلاصة القول في جملة واحدة: القاعدة العامة هي المتغير البيئي > حقل الإعدادات (كلام المدير يتفوق على الكتيب)؛ ولكن هناك استثناءات مثل النموذج — حيث يتفوق أمر
/modelومعامل--model(الطلبات الفورية المباشرة) على المتغير البيئيANTHROPIC_MODEL؛ والسر هو "كلما كان الطلب فورياً ومباشراً، ملك الأولوية القصوى"، وراجع التوضيح الرسمي عند الشك.
06 العمل: ضبط متغير والتحقق من تأثيره وعمله بنفسك
الكلام بدون تطبيق يجعل المتغيرات البيئية تبدو غامضة دائماً. سنقوم الآن بتشغيل تطبيق عملي بسيط: ضبط متغير ← الدخول للمحادثة ← التحقق من تأثيره. ولن نحتاج لتكوينات معقدة، وسننهي الأمر في دقائق.
سنستخدم متغير BASH_DEFAULT_TIMEOUT_MS (المهلة الافتراضية لأوامر bash) للتجربة — لأنه آمن، وسهل الملاحظة، ولا يؤثر على عملية الاتصال عند الخطأ.
الخطوة الأولى: رؤية الحالة الافتراضية أولاً (في الطرفية وقبل تشغيل claude)
دون ضبط أي شيء، افتح محادثة مباشرة:
claudeوبعد الدخول، اطلب منه إخبارك بالمهلة الافتراضية لأوامر bash حالياً:
我现在的 bash 命令默认超时是多少毫秒?读一下你环境里的 BASH_DEFAULT_TIMEOUT_MS,没设的话就说默认值المتوقع: سيخبرك بأن المتغير غير محدد صراحة، وأنه يعتمد على القيمة الافتراضية وهي 120000 (دقيقتان). احفظ هذه القيمة الأساسية لمقارنتها لاحقاً. ثم اخرج من المحادثة (عبر /exit أو الضغط على Ctrl+C مرتين).
الخطوة الثانية: ضبط متغير مؤقت في shell ثم فتح المحادثة
عد للطرفية، وقم بكتابة أمر export لضبط قيمة مختلفة (ولنختر 5 دقائق مثلاً)، ثم افتح المحادثة فوراً:
export BASH_DEFAULT_TIMEOUT_MS="300000"
claudeلمستخدمي Windows PowerShell استخدم الأمر:
$env:BASH_DEFAULT_TIMEOUT_MS = "300000"ثم تشغيلclaude.
وبعد الدخول، اطرح نفس السؤال مجدداً:
我现在的 bash 命令默认超时是多少毫秒?المتوقع: سيقرأ القيمة الجديدة وهي 300000 (5 دقائق)، بدلاً من القيمة الافتراضية 120000. ورؤية تحول الرقم من 120000 إلى 300000 يعبر عن نجاح قراءة إعدادك المؤقت. وهذا يثبت نجاح "الطريقة الأولى: الضبط المؤقت في shell".
الخطوة الثالثة: التحقق من زوال الإعداد بمجرد إغلاق الطرفية
اخرج من المحادثة، وأغلق نافذة الطرفية الحالية بالكامل، وافتح نافذة جديدة تماماً، وشغل claude مباشرة (دون كتابة أمر export)، واطرح نفس السؤال مجدداً.
المتوقع: يعود الرقم للقيمة الافتراضية 120000. لأن تأثير أمر export انتهى بإغلاق نافذة الطرفية المحددة — وهذا يثبت صحة ما ذكرناه في القسم 02 حول زوال الضبط المؤقت بإغلاق الطرفية.
الخطوة الرابعة (اختيارية): كتابة المتغير في settings.json لجعله دائماً
إذا كنت تريد بقاء هذا الإعداد بشكل دائم وبغض النظر عن طريقة تشغيلك، فاكتبه في ملف settings.json. والأسلم هو كتابته في الملف المحلي المخصص لك والذي لا يرفع لـ git:
{
"env": {
"BASH_DEFAULT_TIMEOUT_MS": "300000"
}
}اكتبه داخل
.claude/settings.local.json(في جذر المشروع الحالي ولا يرفع لـ git)، أو داخل~/.claude/settings.json(في مجلد المستخدم الرئيسي ليعمل في كل المشاريع)، بحسب النطاق الذي تفضله — بناءً على جدول القسم 03.
بعد حفظ الملف، افتح طرفية جديدة وشغل claude مباشرة (دون export)، واطرح السؤال مجدداً — لتجده يقرأ الرقم 300000 بثبات، ويستمر كذلك في كل مرة تشغل فيها claude لاحقاً. وهذه هي ميزة "الطريقة الثالثة: الكتابة في settings.json" مقارنة بالضبط المؤقت في shell: تكتبها مرة واحدة لتستمر دائماً.
بتشغيل الخطوات الأربع، تكون قد مررت بالمسار الكامل للمتغيرات البيئية "ضبط ← تحقق من التأثير ← تحقق من النطاق ← التثبيت الدائم". وفي المستقبل، ستتبع نفس المسار عند ضبط أي متغير: تجربه مؤقتاً للتأكد من عمله، ثم تنقله لملف settings.json لتثبيته.
💡 خلاصة القول في جملة واحدة: للتحقق من عمل متغير بيئي، فإن الطريقة الأضمن هي "سؤال Claude عن القيمة التي يقرأها"؛ وجرب كتابته مؤقتاً في shell أولاً (يزول بإغلاق الطرفية)، ثم ثبته في ملف
settings.jsonليستمر دائماً — وتجربتك لهذا المسار بنفسك تزيل أي غموض حول المتغيرات البيئية.
07 خلاصة
غصنا في هذا الدرس تحت السطح، وتعرفنا على لوحة "المفاتيح الرئيسية" التي تدير سلوكيات Claude Code الأساسية — وهي المتغيرات البيئية — وقمنا بضبطها وفهم طريقة عملها.
لنلخص النقاط الأساسية الخمس التي شرحناها: دورها، أين تضبطها، أي الملفات تختار، أشهر المتغيرات، ولمن تكون الغلبة عند التنافس. في جدول واحد:
| ما يجب فهمه | الإجابة | النقاط الرئيسية |
|---|---|---|
| دور المتغيرات البيئية | إدارة السلوكيات الأساسية مثل الاتصال والمصادقة والمهلة والخصوصية | مفاتيح تشغيل قيمية يقرأها عند بدء التشغيل "تضبط مرة واحدة وتعمل طويلاً" |
| أين تضبطها | مؤقتاً في shell / بشكل دائم في ~/.zshrc / في حقل env بملف settings.json | اختر بحسب نطاق التأثير، ويفضل استخدام settings.json للاستخدام الطويل |
| أي ملف settings تختار | مجلد المستخدم الرئيسي / جذر المشروع (يرفع لـ git) / ملف .local (لا يرفع لـ git) | لا تضع البيانات الحساسة وشهادات الدخول في الملفات التي ترفع لـ git |
| أشهر المتغيرات | عائلة ANTHROPIC_* و API_TIMEOUT_MS و DISABLE_TELEMETRY و CLAUDE_CONFIG_DIR | لكل منها قيمة افتراضية، ويتطلب تعديلها إعادة تشغيل claude لتفعيلها |
| من يملك الكلمة العليا | المتغير البيئي يتفوق على حقل الإعدادات؛ ولكن أمر /model يتفوق على ANTHROPIC_MODEL | الطلب الأكثر وضوحاً وحضوراً أثناء العمل يملك الأولوية القصوى دائماً |
يجب أن تكون قادراً الآن على: فهم دور المتغيرات البيئية في إدارة سلوكيات Claude Code الأساسية، ومعرفة نطاق تأثير كل طريقة من الطرق الثلاث للضبط، والتمييز بين ملفات إعدادات settings.json الأربعة وأيها يرفع لـ git، والتعرف على أشهر متغيرات الاتصال والمهلة والخصوصية والحسابات المتعددة، وتحديد الغلبة والأولويات عند ضبط الإعداد في أكثر من مكان. والأهم من ذلك — أنك قمت بضبط متغير والتحقق من تأثيره بنفسك وملاحظة الفارق بين الإعداد المؤقت في shell والإعداد الدائم في ملف التهيئة. وبمجرد زوال هذا الغموض، ستتحول المتغيرات البيئية من طلاسم معقدة إلى مفاتيح سهلة تديرها وتطوعها لخدمتك.
ونعيد التأكيد على العبارة الأولى: المتغيرات البيئية لم تكن يوماً حكراً على المحترفين، بل هي إعدادات تضبطها مرة واحدة لتستفيد منها دائماً. وكل التكرار والجهد الذي كنت تبذله في الجلسات السابقة لضبط الإعدادات يدوياً، يمكنك الآن التخلص منه نهائياً عبر متغير بيئي واحد وتثبيته للأبد.
الدرس القادم 43 "سير عمل Git" — بعد أن رتبت إعدادات وسلوكيات Claude Code الأساسية باستخدام المتغيرات البيئية، يحين الوقت لربطه وتضمينه في سير عملك التطويري اليومي. وعند الحديث عن التطوير، فإن Git هو المحور الأساسي دائماً: كتابة رسائل الالتزام، وفهم الفروق (diff)، وفتح طلبات السحب (PR)، وحل تعارضات الدمج... إلى أي مدى يستطيع Claude مساعدتك في Git، وما هي الفخاخ التي يجب أن تنتبه إليها بنفسك؟ سنتحدث عن ذلك بالتفصيل. فكر في الأمر: قد ترتاح لترك الذكاء الاصطناعي يقوم بعمل git commit بالنيابة عنك، ولكن هل تجرؤ على تركه يضغط على git push لفرع الإنتاج الفعلي دون رقابة؟