Deepseek ArtifactsDeepseek Artifacts
دليل الإعدادات

إعدادات Claude Code: دليل ملف settings.json

كل مفاتيح settings.json الجديرة بالاهتمام: ملفات الإعداد الأربعة وأسبقيتها، والنموذج ومستوى الجهد، وقواعد allow/deny في الأذونات، وكتلة env، وسير عمل حقيقي لتنظيف settings.local.json — كلها موثّقة من الوثائق الرسمية.

ابدأ الجولةانتقل إلى الأسئلة الشائعة

TL;DR

  • أربعة ملفات وتسلسل واحد: managed-settings.json يغلب سطر الأوامر الذي يغلب ‎.claude/settings.local.json الذي يغلب ‎.claude/settings.json الذي يغلب ‎~/.claude/settings.json. وقوائم السماح تُدمَج عبر الملفات بدل أن تُلغي بعضها.
  • ملف settings.json هو JSON صارم: لا تعليقات ولا فواصل زائدة في النهاية. أضِف السطر "$schema": "https://json.schemastore.org/claude-code-settings.json" وسيُكمل محررك كل مفتاح تلقائيًا.
  • قواعد المنع تربح دائمًا. قاعدة منع واحدة في أي مستوى تلغي كل قواعد السماح — ابدأ بـ Read(./.env) وBash(git push:*) وتكون قد حميت أسرارك ومستودعك البعيد في سطرين.
  • ‏settings.local.json هو صندوق الرمل الخاص بجهازك وحده: يغلب إعدادات المشروع المشتركة ويُدرَج تلقائيًا في .gitignore، فلا تتسرب مساراتك الشخصية وتجاربك إلى المستودع أبدًا.

Claude Code Configuration EP1: The Global Files Decoded (settings.json, CLAUDE.md, skills)

القناة: Terminode AI2:31

مشاهدة

Learning In Public: Cleaning Up Claude Code Settings

القناة: Ben Nadel5:26

مشاهدة

Settings — official documentation

الوثائق الرسمية: code.claude.com/docs

مشاهدة

Settings reference — the full key table

الوثائق الرسمية: code.claude.com/docs

مشاهدة

Environment variables — official reference

الوثائق الرسمية: code.claude.com/docs

مشاهدة

حقائق هذه الصفحة موثقة من وثائق الإعدادات الرسمية؛ والفيديوان أعلاه هما المصدران البصريان وإلهام سير عمل التدقيق.

تُنسب لقطات الشاشة إلى صانعيها بروابط مباشرة إلى الطوابع الزمنية الدقيقة. لا تُستخدم لقطات للوجوه.

اضبط settings.json في Claude Code خطوة بخطوة

الجزء 1 — ارسم خريطة مشهد الإعدادات

  1. 1

    اعرف ملفات الإعدادات الأربعة

    يقرأ Claude Code الإعدادات من أربعة نطاقات: ‎~/.claude/settings.json (أنت، في كل مشروع)، و‎.claude/settings.json (مشترك مع الفريق، أودِعه في Git)، و‎.claude/settings.local.json (أنت، في هذا المشروع فقط)، وmanaged-settings.json (مؤسستك). وكل ما داخل ‎~/.claude — من CLAUDE.md وprojects وskills وagents وplugins — جزء من المشهد نفسه.

    Claude Code global config map card listing settings.json, CLAUDE.md, projects, skills, agents, plugins and the .claude.json state file inside the ~/.claude directory
    الطبقة العامة في لمحة: كل ملف يقرأه Claude Code من ‎~/.claude عند بدء الجلسة.شاهد عند 2:28
  2. 2

    افتح ‎~/.claude/settings.json أو أنشئه

    على Mac وLinux يعيش الملف في ‎~/.claude/settings.json، وعلى Windows هو ‎%USERPROFILE%\.claude\settings.json. أنشئه إن لم يكن موجودًا — سيلتقطه Claude Code في الجلسة التالية. واضبط CLAUDE_CONFIG_DIR إن أردت مجلد الإعدادات كله في مكان آخر.

    Claude Code settings.json card showing the ~/.claude/settings.json path on Mac and Linux and the Windows USERPROFILE location for themes, model choice and permissions
    يتحكم settings.json في السِمات واختيار النموذج والإضافات ومتغيرات البيئة والأذونات عبر كل مشاريع جهازك.شاهد عند 0:20
  3. 3

    ثبّت نموذجك ومستوى الجهد

    اجعل "model" نموذجًا بعينه أو "opusplan" (‏Opus يخطط وSonnet ينفّذ) فيصير الافتراض لكل جلسة جديدة — وهو الاختيار نفسه الذي يفعله /model تفاعليًا. اقرنه بـ "effortLevel" لتحديد سقف تفكير Claude افتراضيًا، وبـ modelSettings للتجاوزات الخاصة بكل نموذج.

  4. 4

    اسمح بالأوامر التي تثق بها

    داخل كتلة permissions يسرد "allow" قواعد أدوات تتخطى نافذة الموافقة: "Bash(npm run lint)" و"Bash(npm run test *)" و"Read(~/.zshrc)". القواعد أنماط مقيّدة بأداة — والرمز البديل * يحتاج مسافة قبله ("Bash(git push:*)") كي لا يبتلع أسماء أوامر أطول.

    Claude Code settings.local.json permissions allow list open in VS Code showing Bash git commands and WebFetch domain allow entries
    قائمة سماح حقيقية من settings.local.json: كل مدخل هنا كان نافذة موافقة لن تظهر ثانية.شاهد عند 0:50

الجزء 2 — الأذونات وenv والتجاوزات

  1. 5

    احمِ الأسرار بقواعد المنع

    تُقيَّم قواعد المنع أولًا ولا شيء في أي مستوى يمكن أن يلغيها. ابدأ بـ "Read(./.env)" و"Read(./.env.*)" كي لا تدخل مفاتيح API في السياق أبدًا، ثم "Bash(git push:*)" كي يبقى النشر إلى المستودع البعيد قرارًا بشريًا. وبعدها دع قواعد ask تمسك المنطقة الرمادية.

  2. 6

    احفظ التجاوزات المحلية لجهازك في settings.local.json

    حين يسجّل Claude Code إذنًا نيابة عنك يهبط إلى ‎.claude/settings.local.json — وهو أيضًا يدرجه تلقائيًا في .gitignore. استخدم هذا الملف للمسارات الشخصية وأعلام التجارب وكل ما لا تريد فرضه على زملائك. أما القواعد المشتركة والمقصودة فمكانها ‎.claude/settings.json.

  3. 7

    ضع الأسرار والمفاتيح في كتلة env

    يطبّق كائن "env" متغيرات البيئة على كل جلسة: "ANTHROPIC_API_KEY" و"DISABLE_TELEMETRY": "1" و"DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1" أو CLAUDE_CODE_MAX_OUTPUT_TOKENS. وقاعدة عملية مفيدة من الوثائق: المفاتيح بأحرف كبيرة داخل settings.json تعود إلى env في الغالب.

  4. 8

    لا تخلط بين ‎~/.claude.json والإعدادات

    ‏~/.claude.json حالة وليست إعدادات: رموز OAuth وتسجيلات خوادم MCP وقرارات الثقة لكل مشروع ومفاتيح عامة تسكن هناك. عدّل settings.json للتعبير عن قصدك، ودَع Claude Code يدير .claude.json بنفسه — واعمل نسخة احتياطية للملفين، لأن cleanupPeriodDays يحكم أيضًا كم يبقى تاريخ النصوص.

    Terminal listing of the ~/.claude folder in Claude Code showing statsig feature flags, the plugins directory, shell snapshots and the .claude.json global state file
    داخل ‎~/.claude: أعلام ميزات وإضافات ولقطات shell وملف الحالة .claude.json الذي يسهل الخلط بينه وبين ملف الإعدادات.شاهد عند 2:00

الجزء 3 — حافظ على النظافة مع الزمن

  1. 9

    اعرف ما يسكن أيضًا في ‎~/.claude

    ‏CLAUDE.md ملف تعليماتك العام، يُقرأ في بداية كل جلسة. يخزّن projects/ تاريخ المحادثات والذاكرة التلقائية لكل مستودع، ويحتوي skills/ سير عمل SKILL.md عند الطلب، ويعرّف agents/ الوكلاء الفرعيين، ويتتبع plugins/ الإضافات المثبتة، ويخزّن statsig/ أعلام الميزات مؤقتًا. و settings.json ينسّقها جميعًا.

    Claude Code CLAUDE.md global instruction file card with personal preferences, code style rules and testing patterns loaded at the start of every session
    ‏CLAUDE.md هو الملف الشقيق الذي يخلطه الناس بالإعدادات: يحمل تفضيلات وأعرافًا، لا مفاتيح إعداد.شاهد عند 0:45
  2. 10

    اطلب من Claude تدقيق قائمة السماح لديك

    تنمو قوائم السماح نافذة بعد نافذة حتى لا يذكر أحد ما فيها. افتح Claude Code واطلب منه مراجعة .claude/settings.local.json بحثًا عن مدخلات مكررة أو غير ضرورية أو محفوفة بالمخاطر — فـ Claude يعرف أي الأدوات مدمجة فيه وأي القواعد تتقاطع.

    Claude Code prompt asking Claude to review the permissions allow list in settings.local.json for redundant and overly permissive entries
    نافذة التدقيق: راجع قائمة السماح، وأشِر إلى ما هو مكرر، وما يضاعف أدوات مدمجة، وما هو خطِر ببساطة.شاهد عند 1:40
  3. 11

    اقرأ الحكم بعين مراجع

    في التدقيق الحقيقي الذي تصوّره هذه الصفحة وجد Claude 41 مدخلًا وصفّها: ls وgrep وfind وecho وcd تضاعف أدوات مدمجة؛ ومدخلات الرمز البديل كانت تغطي أوامر صريحة أصلًا؛ والمسارات المطلقة المحلية كانت زائدة لأن Claude يعرف مجلد عمله؛ أما curl فهي الوحيدة التي وُسمت بأنها متسعة فعلًا أكثر من اللازم.

    Claude Code analysis table flagging unnecessary Bash ls, grep and find permission entries that duplicate built-in tools in settings.local.json
    الحكم: 41 مدخلًا صفّت إلى غير ضروري ومكرر وخطِر — مع البديل عن كل سطر.شاهد عند 3:05
  4. 12

    طبّق التنظيف وأعد الفحص شهريًا

    وافق على التعديلات المقترحة فينكمش الملف من 41 مدخلًا إلى 15. اجعلها عادة: قائمة السماح التي لا تستطيع قراءتها هي سطح هجوم لا تستطيع رؤيته. أعد التدقيق بعد المشاريع الكبيرة، وفضّل القواعد المقيّدة مثل Bash(git diff:*) على الموافقات الشاملة.

    Claude Code summary of permission changes removing curl, explicit home directory paths and one-off shell script entries from the settings allow list
    التنظيف المطبق: curl والمسارات المنزلية الصريحة وسكربتات shell للاستخدام الواحد خرجت من قائمة السماح.شاهد عند 4:50

‏settings.json مقابل CLAUDE.md مقابل ‎~/.claude.json مقابل ‎/config

أربع واجهات تبدو كلها وكأنها «إعدادات Claude Code» — لكنها ليست قابلة للتبادل. أي ملف يملك ماذا:

  • 1‏settings.json (كل النطاقات) — إعداد تعريفي: model وeffort وpermissions وenv وhooks وstatusLine وplugins. ‏JSON صارم، متحقق منه بالمخطط، وآمن للإيداع في Git (عدا نسخة .local).
  • 2‏CLAUDE.md — تعليمات وأعراف بلغة طبيعية. تشكّل السلوك لا الإعدادات؛ لا عقد مفاتيح وقيم فيها، وتُقرأ في كل جلسة.
  • 3‏~/.claude.json — حالة الجهاز: بيانات OAuth والجلسات، وتسجيلات MCP، والثقة لكل مشروع، وأعلام التهيئة. يكتبه Claude Code؛ فلا تعدّله يدويًا.
  • 4‏/config — اللوحة التفاعلية. هي واجهة فوق المفاتيح نفسها: معظم المفاتيح تكتب في ‎~/.claude/settings.json، وقِلة (مثل Show tips) تذهب إلى settings.local.json، والخيارات العامة تهبط في ‎~/.claude.json.
  • 5‏managed-settings.json — طبقة المؤسسة. تلغي كل شيء (باستثناءات أمنية قليلة يغلب فيها الأشد صرامة)، ولهذا قد يخسر اختيارك المحلي للنموذج بصمت على جهاز العمل.

قاعدة إرشادية: السلوك في CLAUDE.md، والإعدادات في settings.json، وإذا بدت قيمة متجاهلة لك فتحقق مما إذا كانت ‎~/.claude.json أو ملفًا مُدارًا قد حسم القرار.

الإعدادات لا تُطبَّق؟ الإسعافات الأولى

معظم مشكلات settings.json ترجع إلى خمسة أسباب. اعالجها بالترتيب:

  • 1أخطاء صياغة JSON. ملف settings.json هو JSON صارم — فاصلة زائدة في النهاية أو تعليق // ويرفض الملف كله. الصقه في مدقق، أو أضِف سطر $schema ليؤشر محررك على الأخطاء أثناء الكتابة.
  • 2قاعدة أشد فوقك. الإعدادات المُدارة والمفاتيح الحساسة أمنيًا (مثل disableClaudeAiConnectors أو useAutoModeDuringPlan) تغلب ملفك مهما فعلت. تحقق مما إذا كان جهاز العمل يتجاوزك.
  • 3ملف خاطئ، نطاق خاطئ. قواعد ‎.claude/settings.json تسري داخل ذلك المشروع فقط؛ وقيم defaultMode مثل auto وbypassPermissions تُتجاهل عمدًا في ملفات مستوى المشروع.
  • 4قيم env في المكان الخطأ. المفاتيح بأحرف كبيرة مكانها كتلة env لا المستوى الأعلى. إن بدت ANTHROPIC_API_KEY أو DISABLE_TELEMETRY متجاهَلة فهي على الأرجح مستقرّة مستوى واحدًا أعلى من اللازم.
  • 5مدخلات مرفوضة بصمت. شغّل claude doctor لسرد مدخلات الإعدادات التي رسبت في التحقق، و/status داخل جلسة لترى أي الملفات حُمّلت فعلًا.

ما زلت عالقًا؟ احذف آخر تعديل، وتأكد بأن الملف يُحمَّل عبر /status، ثم أعد تطبيق التغيير مفتاحًا مفتاحًا — تجزيء الملف خير من التحديق فيه.

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

أدلة Claude Code ذات الصلة

اختصارات Claude Code ووضع vimدليل إعداد statusline في Claude Codeدليل أذونات Claude Codeبرنامج تعليمي عن Claude Code hooksالضغط التلقائي في Claude Codeحدود استخدام Claude Code بالتفصيل