دليل Claude Code التعليمي: التثبيت والتشغيل (2026)

أقصر مسار من التثبيت إلى أول تشغيل: أمر واحد يهيئ Claude Code مع QCode، ثم أضف مفتاحك cr_ وابدأ. دليل تعليمي كامل لعام 2026.

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

آخر تحقق: 2026-10-20 · 📄 وفق الوثائق الرسمية وqcode.cc (إعداد Claude Code؛ صفحة التثبيت بنقرة واحدة من QCode؛ تم التحقق في 2026-10-20)

أقصر مسار

# macOS / Linux
curl -fsSL https://qcode.cc/install/claude-code.sh | bash

# Windows PowerShell
irm https://qcode.cc/install/claude-code.ps1 | iex

1. شغّل الأمر المناسب لنظامك.
2. الصق مفتاح API الذي يبدأ بـ cr_ عند المطالبة: يختبر السكربت زمن استجابة نقطة النهاية، ويكتب الإعدادات، ويثبّت Node.js إذا كان مفقودًا، ثم يرسل في النهاية طلبًا واحدًا بالحد الأدنى للتحقق من الاتصال.
3. شغّل claude عند انتهاء تنفيذه. تتبع واجهة السكربت لغة نظامك وتنتقل بين الإنجليزية والصينية.

هذا دليل تعليمي شامل عن Claude Code مصمم للمطورين. سواء كنت جديدًا على أدوات البرمجة بالذكاء الاصطناعي أو تنتقل من أدوات أخرى، سيساعدك هذا الدليل على إتقان Claude Code — أقوى مساعد برمجة بالذكاء الاصطناعي في 2026.

1. ما هو Claude Code¶

مساعد برمجة وكيلي، وليس إكمالًا للشيفرة¶

Claude Code هو مساعد البرمجة الوكيلي الرسمي من Anthropic عبر CLI. وخلافًا لأدوات إكمال الشيفرة التقليدية مثل GitHub Copilot، فإنه يتصرف كمطوّر ذي خبرة:

• يفهم المهمة من تلقاء نفسه: تصف ما تريد، فينتج خطة
• يعمل على الشيفرة مباشرة: يقرأ ويعدّل وينشئ أي ملف في المشروع
• يشغّل أوامر الطرفية: الاختبارات، وتثبيت الاعتماديات، وعمليات البناء
• يفهم المشروع بعمق: نافذة سياق افتراضية بسعة 200K token (تمتد claude-opus-5 / claude-sonnet-5 وغيرها إلى 1M)
• يوزّع وكلاء فرعيين: يقسّم مهمة معقدة على عدة وكلاء فرعيين متخصصين يعملون بالتوازي

من يستخدمه¶

منذ إصداره في مايو 2025، أصبح Claude Code أداة تطوير أساسية في شركات رائدة حول العالم، منها Netflix وSpotify وKPMG وL'Oréal وSalesforce. ووصل إلى إنجاز الإيرادات السنوية البالغة $1B في ستة أشهر فقط.

التحديثات الرئيسية في 2025-2026¶

لماذا تمر عبر QCode.cc¶

استخدام Claude Code مباشرة من البر الرئيسي للصين يواجه مشكلتين: الشبكة غير قابلة للوصول والتكلفة مرتفعة. عبر QCode.cc:

• زمن استجابة منخفض على عقد آسيا والمحيط الهادئ — لا حاجة إلى خادم وسيط مستضاف ذاتيًا
• الفوترة حسب token — تُدرج أسعار كل نموذج في qcode.cc/models
• يتشارك Claude Code وCodex حصة خطة واحدة — خطة واحدة، أداتان
• توافر عالٍ عبر العقد (آسيا / أمريكا الشمالية وأوروبا / Route 53 العالمية)

2. التثبيت والإعداد¶

متطلبات النظام¶

يعمل Claude Code أصليًا على Windows أو داخل WSL؛ ولا يحتاج المثبّت الأصلي أدناه إلى Node.js؛ بينما تتطلب حزمة npm الإصدار 22 أو أحدث من Node.js (الوثائق الرسمية، تم التحقق في 2026-10-20).

تثبيت Claude Code¶

الطريقة الموصى بها رسميًا حاليًا هي Native Install (تم التحقق في 2026-10-20):

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Homebrew
brew install --cask claude-code

لا يزال npm يعمل:

# npm install (still available)
npm install -g @anthropic-ai/claude-code

# Users in China can speed this up with the Taobao mirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

إعداد QCode.cc¶

عيّن متغيرات البيئة في الطرفية:

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
export ANTHROPIC_AUTH_TOKEN=cr_your_api_key

لماذا ANTHROPIC_AUTH_TOKEN وليس ANTHROPIC_API_KEY: مفتاح QCode.cc الذي يبدأ بـ cr_ هو مفتاح بوابة لجهة خارجية، وليس مفتاح Anthropic رسميًا. عندما يرى Claude Code ANTHROPIC_AUTH_TOKEN فإنه يرسل Authorization: Bearer <token> إلى البوابة؛ ومع ANTHROPIC_API_KEY يرسل x-api-key بدلًا من ذلك، وهو ما قد يتعارض مع جلسة OAuth لحساب Anthropic مسجّل الدخول إليه بالفعل. استخدام ANTHROPIC_AUTH_TOKEN هو توصية QCode الرسمية.

احصل على مفتاح API من لوحة تحكم QCode.cc؛ يبدأ بـ cr_.

اختيار نقطة النهاية: القيمة الافتراضية هي https://api.qcode.cc/api (يختار Route 53 العالمي أقرب عقدة تلقائيًا). ينبغي للمستخدمين في البر الرئيسي للصين تفضيل asia.qcode.cc (عقدة آسيا، الأقرب من كوريا / تايوان / هونغ كونغ، وأقل زمن وصول). تُغطّى النطاقات الأخرى (us / asia) وقواعد BASE_URL في نقاط النهاية وتنسيقات API.

طبّق الإعداد:

source ~/.bashrc  # or source ~/.zshrc

التحقق من التثبيت¶

# Check the version
claude --version
# Prints a version number (yours may differ, see https://github.com/anthropics/claude-code/releases)

# Quick test
claude -p "Hello, please introduce yourself"

إذا ردّ Claude، فقد نجح التثبيت والإعداد.

إكمال الصدفة (اختياري)¶

# Bash
claude completion bash >> ~/.bashrc

# Zsh
claude completion zsh >> ~/.zshrc

# Fish
claude completion fish > ~/.config/fish/completions/claude.fish

3. الاستخدام الأول¶

البدء¶

شغّله في أي دليل مشروع:

cd ~/my-project
claude

يفحص Claude Code بنية المشروع تلقائيًا ويدخل الوضع التفاعلي.

فحص أدنى بعد التشغيل¶

# Confirm the CLI is ready
claude --version

# Run one minimal non-interactive request
claude -p "In one sentence, what does this project do?"

إذا عاد كلا الأمرين بشكل طبيعي، فإن CLI وتكوين QCode كلاهما فعّال.

قراءة الواجهة¶

╭─────────────────────────────────────────╮
│ claude                                   │
│                                          │
│ Project: my-project                      │
│ Model: claude-sonnet-5                   │
│ Context: 12,345 / 1,000,000 tokens       │
╰─────────────────────────────────────────╯

> _

اكتب بلغة عادية — سيفهم Claude ويتصرف.

المهمة الأولى: فهم المشروع¶

> Analyse this project's architecture and tell me the main modules and how they relate

يقوم Claude تلقائيًا بما يلي: 1. يقرأ package.json وREADME.md وبنية الدليل 2. يستعرض ملفات المصدر الأساسية سريعًا 3. ينتج تحليلًا منظمًا للبنية

رسائل طلب الأذونات¶

عندما يريد Claude تنفيذ إجراء، يطلب منك التأكيد:

Claude wants to run:
  Tool: Bash
  Command: npm test

  [y] allow  [n] deny  [a] always allow in this session

• y: السماح بهذه المرة
• n: الرفض
• a: السماح دائمًا بهذا النوع من الإجراءات لبقية الجلسة (مفيد للتطوير اليومي)

أوضاع الأذونات الشائعة¶

4. الميزات الأساسية¶

4.1 وضع الخطة¶

يجعل وضع الخطة Claude يبحث ويحلل أولًا ثم لا يقترح خطة إلا بعد ذلك. وهو مناسب للمهام المعقدة.

# Enter plan mode
> /plan

# Or trigger it from the prompt
> Analyse the requirements and draft a plan first — don't change any code yet

كيف يعمل: 1. يحلل Claude قاعدة الشيفرة والمتطلبات 2. يقترح خطة (أي الملفات تُنشأ/تُعدّل، وبأي ترتيب) 3. تراجع الخطة وتطلب تغييرات 4. بعد التأكيد، ينفّذها Claude

مثال:

> /plan
> I want to add JWT-based user authentication to this project

Claude: Let me analyse the current project structure and draft a plan...

📋 Plan:
1. Create src/middleware/auth.ts — JWT verification middleware
2. Create src/services/auth-service.ts — authentication business logic
3. Modify src/routes/index.ts — add login/register routes
4. Create src/models/user.ts — user data model
5. Add dependencies: jsonwebtoken, bcrypt
6. Create test files

Does this plan work? Anything to adjust?

4.2 التفكير الموسّع¶

يمتلك Opus 5 (و4.8 / 4.7، ما زالا معروضين للبيع) تفكيرًا موسّعًا مدمجًا — نوصي بالتفكير التكيفي إلى جانب معامل الجهد، راجع دليل إعداد التفكير التكيفي. عند المشكلات الصعبة، يفكر بعمق داخليًا أولًا.

> I've been chasing this concurrency bug for two days. Analyse the race condition in src/worker.ts

[Claude reasons internally for thousands of tokens, walking execution paths, locking and timing]

Claude: Found it. On line 127 of worker.ts...

متى يُفعّل تلقائيًا:

• تصحيح الأخطاء المعقد
• التحليل على مستوى البنية
• سلاسل الاستدلال متعددة الخطوات

4.3 الوكلاء الفرعيون¶

يستطيع Claude إنشاء وكلاء فرعيين متخصصين لمهام محددة:

> Review this PR for me, and check for security issues at the same time

Claude: I'll start two subagents in parallel:

  - Subagent 1: code quality review
  - Subagent 2: security vulnerability scan

يعمل الوكلاء الفرعيون في سياقهم الخاص، لذا لا يلوّثون الجلسة الرئيسية.

4.4 الأوامر الأساسية¶

4.5 إدارة السياق¶

يمتلك Claude Code نافذة سياق بسعة 200K token. تحتاج الجلسات الطويلة إلى إدارة:

# Check current context usage
/cost

# Compact the context (keep what matters, free space)
/compact

# Start a completely new session
/clear

أفضل الممارسات:

• شغّل /compact عندما يتجاوز استخدام السياق 70%
• ابدأ جلسة جديدة باستخدام /clear عند تبديل المهام
• في المشاريع المعقدة، احتفظ بالمعلومات الخلفية في CLAUDE.md (لا يزيلها /compact أبدًا)

5. CLAUDE.md — إعدادات المشروع¶

لماذا تحتاج إلى CLAUDE.md¶

في كل مرة يبدأ فيها Claude Code، يقرأ ملف CLAUDE.md الخاص بالمشروع ليتعرّف على البنية ومعايير البرمجة والاصطلاحات المحلية. ومن دونه تعيد شرح المشروع في كل جلسة.

أنشئه بسرعة¶

# Claude analyses the project and generates the file
/init

هرمية الملفات¶

قالب عملي: مشروع React + TypeScript¶

# MyApp

## Tech Stack

- React 19 + TypeScript 5.x + Vite
- Styling: Tailwind CSS v4
- State: Zustand
- Testing: Vitest + Testing Library

## Commands

- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Coding Standards

- Function components only; define Props with an interface
- The any type is not allowed
- CSS through Tailwind utility classes only
- Commit format: feat: / fix: / docs:

## Project Structure

- src/components/ — reusable components
- src/pages/ — page components
- src/hooks/ — custom hooks
- src/lib/ — utility functions
- src/api/ — API request wrappers

## Notes

- Node.js 22+, pnpm as the package manager
- All API requests go through src/api/client.ts

للاطّلاع على الدليل الكامل، راجع إعدادات CLAUDE.md.

6. اختيار النموذج¶

مقارنة النماذج الثلاثة¶

تُحسب الفاتورة لكل token؛ وتُدرَج أسعار كل نموذج على qcode.cc/models (تم التحقق في 2026-10-20). لا تزال نماذج 4.x معروضة للبيع، لكنها ببساطة لم تعد الافتراضية.

تبديل النماذج¶

# Switch inside an interactive session
/model opus    # switch to Opus
/model sonnet  # switch to Sonnet
/model haiku   # switch to Haiku

# Specify at launch
claude --model claude-opus-5

توصيات حسب السيناريو¶

استراتيجية مختلطة (موصى بها)¶

A day's model usage:
├── Sonnet 5 (70%) — everyday development, bug fixes, tests
├── Opus 5  (15%) — architecture decisions, hard problems
└── Haiku 4.5 (15%) — formatting, simple questions, bulk operations

يمكنك التبديل في أي نقطة أثناء المحادثة:

# Plan with Opus first
/model opus
> Analyse this module's architecture and draft a refactoring plan

# Once the plan is agreed, switch to Sonnet to execute
/model sonnet
> Carry out step one of the plan

7. نصائح متقدمة¶

الخطافات¶

اضبط خطافات الأتمتة في .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}

الدليل الكامل: نظام الخطافات.

خوادم MCP¶

اربط الأدوات الخارجية عبر بروتوكول سياق النموذج:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    }
  }
}

المهارات¶

المهارات وحدات معرفية قابلة لإعادة الاستخدام:

# List available skills
/skills

# Use a specific skill
> Commit these changes    # natural language; /commit needs a custom command or skill, not built-in
> /review    # review code with the review skill

وضع --bare¶

استدعاء عبر سكربت مع تخطي كل الميزات التفاعلية:

claude --bare -p "List every TODO comment" --output-format json

8. أمثلة عملية¶

المثال 1: فهم قاعدة شيفرة جديدة¶

cd ~/unfamiliar-project
claude

> Analyse this project:
> 1. which technologies it uses
> 2. the core modules and their responsibilities
> 3. how data flows through it
> 4. draw a simple architecture diagram (ASCII)

يتصفح Claude ملف package.json ومجلدات المصدر وملفات الإعداد، وينتج خريطة كاملة للمشروع.

المثال 2: تنفيذ ميزة باستخدام Plan Mode¶

> /plan
> I need to add rate limiting to the API:
> - at most 60 requests per minute per user
> - store counters in Redis
> - return 429 with a Retry-After header when exceeded

Claude:
📋 Plan:
1. Install dependency: ioredis
2. Create src/middleware/rate-limiter.ts
3. Create src/config/rate-limit.ts (settings)
4. Modify src/app.ts (register the middleware)
5. Create tests/rate-limiter.test.ts
6. Update docker-compose.yml (add the Redis service)

Confirm and I'll start.

> The plan looks good, go ahead

المثال 3: تصحيح خطأ صعب¶

/model opus
> Users report that "stock occasionally goes negative when orders are placed concurrently".
> Analyse src/services/order-service.ts and src/services/inventory-service.ts,
> find the concurrency bug and fix it.

[Opus engages Extended Thinking and walks execution paths, locking and transaction isolation levels]

Claude: Found it. On line 45 of inventory-service.ts the stock check and the decrement are not in the same transaction,
which is a TOCTOU race. The fix is to use SELECT FOR UPDATE...

المثال 4: إعادة هيكلة على دفعات¶

> All class components in the project need to become function components + Hooks.
> Work through every .tsx file under src/components/ one at a time.

Claude will:
1. Find every class component
2. Convert them one by one to function components
3. Turn lifecycle methods into useEffect
4. Turn this.state into useState
5. Run the tests to confirm nothing broke

المثال 5: كتابة مجموعة اختبارات كاملة¶

> Write a complete unit test suite for src/services/user-service.ts:
> - cover every public method
> - include both happy and error paths
> - mock external dependencies (database, cache)
> - target 90%+ coverage

المثال 6: أتمتة CI/CD¶

# Inside GitHub Actions
claude -p "Review the code changes in this PR, focusing on security and performance" \
  --output-format json \
  --max-turns 3 \
  --allowedTools Read,Glob,Grep

المزيد من أمثلة CI/CD: الأتمتة وCI/CD.

9. Claude Code وCodex معًا¶

Claude Code وOpenAI Codex CLI هما أقوى أداتَي البرمجة بالذكاء الاصطناعي في 2026، ولكل منهما نقاط قوته.

أفضل توليفة: يتولى Claude Code التخطيط والمراجعة، بينما ينفّذ Codex ويتولى العمل الكثيف.

# 1. Claude Code drafts the plan
claude
> /plan
> Design an implementation plan for the user permission system

# 2. Codex executes it
codex "Follow the plan in PLAN.md and implement steps 1-3"

خطة QCode.cc واحدة، وحصة مشتركة واحدة للأداتين — والتبديل لا يكلّف شيئًا. مقارنة كاملة: Codex مقابل Claude Code. دليل Codex: البرنامج التعليمي الكامل لـ Codex.

هل تعملون ضمن فريق؟ للفرق المكوّنة من ثلاثة أعضاء أو أكثر، نوصي بـ خطة الفرق — نطاق مخصص e-xxx.qcode.cc، وإدارة مفاتيح API الفرعية، وضمان الخدمة، والتحويل المؤسسي. راجع دليل خطة الفرق.

10. الأسئلة الشائعة¶

فشل التثبيت¶

س: يظهر خطأ صلاحيات عند تنفيذ npm install -g

# Option 1: use sudo
sudo npm install -g @anthropic-ai/claude-code

# Option 2: manage Node.js with nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
npm install -g @anthropic-ai/claude-code

مشكلات الشبكة¶

س: تنتهي مهلة الاتصال أو يُرفض الاتصال

# Check the configuration
echo $ANTHROPIC_BASE_URL    # should be https://api.qcode.cc/api
echo $ANTHROPIC_AUTH_TOKEN  # should start with cr_

# Test connectivity
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models
# -> 200 + a JSON model list = address, key and network all fine

التحكم في التكلفة¶

س: أشعر بالقلق بشأن الفاتورة

• استخدم Sonnet يوميًا (توازن بين القدرة والسرعة)
• تحقق من الإنفاق في أي وقت باستخدام /cost
• استخدم /compact لتقليص السياق وخفض استخدام token
• أرسل المهام البسيطة إلى Haiku (خفيف وسريع)
• راجع دليل تحسين التكلفة

Claude لا يفهم المشروع¶

س: يستمر Claude في إساءة قراءة بنية المشروع أو اصطلاحاته

أنشئ ملف CLAUDE.md (راجع الفصل 5) ودوّن فيه خلفية المشروع واصطلاحاته والأوامر الشائعة. يقرأه Claude تلقائيًا عند كل بدء.

كيف يختلف عن الأدوات الأخرى¶

س: كيف يختلف Claude Code عن Cursor / Copilot؟

Claude Code مساعد على مستوى الوكيل (يمكنه إنجاز المهام المعقدة بنفسه)، وليس أداة إكمال على مستوى السطر. تعمل الأداتان معًا بصورة جيدة: Cursor للتحرير والإكمال في الوقت الفعلي، وClaude Code للتخطيط وتنفيذ الأعمال المعقدة.

ملاحظة: يعمل المفتاح cr_ نفسه الخاص بـ QCode.cc مع Claude Code وCodex CLI ومجموعة واسعة من بيئات IDE / واجهات CLI / تطبيقات سطح المكتب، بما في ذلك Cursor. لـ Cursor (Base URL مخصص + مفتاح API) راجع تكامل محرر Cursor؛ مصفوفة البروتوكولات والقائمة الكاملة موجودة في نظرة عامة على توافق الأدوات.

الوثائق ذات الصلة¶

• دليل التثبيت — خطوات التثبيت المفصلة
• إعداد CLAUDE.md — دليل إعداد المشروع الكامل
• نظام Hooks — تفاصيل خطافات الأتمتة
• الأتمتة وCI/CD — استخدام الوضع بلا واجهة
• دليل اختيار النموذج — مقارنة مفصلة بين النماذج
• تحسين التكلفة — تقنيات التحكم في الإنفاق
• Codex مقابل Claude Code — مقارنة بين الأداتين
• البرنامج التعليمي الكامل لـ Codex — دليل Codex الكامل
• الخطط والأسعار — خطط QCode.cc

المؤسسات ←