آموزش 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، ابزار CLI رسمی Anthropic، یک دستیار کدنویسی عاملمحور است. برخلاف ابزارهای سنتی تکمیل کد مانند GitHub Copilot، مانند یک توسعه‌دهنده باتجربه عمل می‌کند:

• خودش وظیفه را می‌فهمد: شما می‌گویید چه می‌خواهید، او یک برنامه می‌سازد
• مستقیماً روی کد کار می‌کند: هر فایلی در پروژه را می‌خواند، ویرایش و ایجاد می‌کند
• فرمان‌های ترمینال را اجرا می‌کند: تست‌ها، نصب وابستگی‌ها، بیلدها
• پروژه را عمیقاً درک می‌کند: به‌طور پیش‌فرض پنجره زمینه 200K توکن (claude-opus-5 / claude-sonnet-5 و مدل‌های دیگر تا 1M گسترش می‌یابند)
• زیرعامل‌ها را اعزام می‌کند: یک وظیفه پیچیده را میان چند زیرعامل تخصصی که به‌صورت موازی اجرا می‌شوند تقسیم می‌کند

چه کسانی از آن استفاده می‌کنند¶

Claude Code از زمان انتشارش در می 2025 به ابزار اصلی توسعه در شرکت‌های پیشرو جهان از جمله Netflix، Spotify، KPMG، L'Oréal و Salesforce تبدیل شده است. این محصول تنها در شش ماه به نقطه عطف درآمد سالانه $1B رسید.

به‌روزرسانی‌های کلیدی در 2025-2026¶

چرا از QCode.cc استفاده کنیم¶

استفاده مستقیم از Claude Code از سرزمین اصلی چین با دو مشکل روبه‌رو می‌شود: شبکه در دسترس نیست و هزینه بالاست. از طریق QCode.cc:

• تأخیر کم روی نودهای آسیا-اقیانوسیه — نیازی به پراکسی خودمیزبان نیست
• صورت‌حساب مبتنی بر توکن — قیمت هر مدل در qcode.cc/models فهرست شده است
• Claude Code و Codex یک سهمیه پلن مشترک دارند — یک پلن، دو ابزار
• دسترس‌پذیری بالا در میان نودها (آسیا / آمریکای شمالی و اروپا / Route 53 جهانی)

2. نصب و راه‌اندازی¶

پیش‌نیازهای سیستم¶

Claude Code به‌صورت بومی روی Windows یا داخل WSL اجرا می‌شود؛ نصب‌کننده بومی زیر به Node.js نیاز ندارد؛ بسته npm به Node.js 22 یا جدیدتر نیاز دارد (مستندات رسمی، بررسی‌شده در 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 Plan Mode¶

Plan Mode باعث می‌شود 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 Extended Thinking¶

Opus 5 (و 4.8 / 4.7 که هنوز به فروش می‌رسند) Extended Thinking توکار دارد — توصیه می‌کنیم از Adaptive Thinking همراه با پارامتر effort استفاده کنید، به راهنمای پیکربندی Adaptive Thinking مراجعه کنید. روی مسائل سخت، ابتدا به‌صورت خصوصی و عمیق استدلال می‌کند.

> 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 Sub-agents¶

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 توکنی دارد. نشست‌های طولانی نیاز به مدیریت دارند:

# Check current context usage
/cost

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

# Start a completely new session
/clear

بهترین روش‌ها:

• وقتی مصرف زمینه از 70% گذشت، /compact را اجرا کنید
• هنگام تغییر وظیفه، با /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. انتخاب مدل¶

مقایسه سه مدل¶

صورت‌حساب به‌ازای هر توکن است؛ نرخ هر مدل در 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. نکات پیشرفته¶

Hooks¶

Hooks‌های خودکارسازی را در .claude/settings.json پیکربندی کنید:

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

راهنمای کامل: Hooks System.

سرورهای MCP¶

ابزارهای خارجی را از طریق Model Context Protocol متصل کنید:

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

Skills¶

Skills ماژول‌های دانش قابل استفاده مجدد هستند:

# 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: Automation & 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 استفاده کنید
• کارهای ساده را به 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 — جزئیات Hooks خودکارسازی
• خودکارسازی و CI/CD — استفاده از حالت headless
• راهنمای انتخاب مدل — مقایسه دقیق مدل‌ها
• بهینه‌سازی هزینه — تکنیک‌های کنترل هزینه
• Codex در برابر Claude Code — مقایسه این دو ابزار
• آموزش کامل Codex — راهنمای کامل Codex
• پلن‌ها و قیمت‌گذاری — پلن‌های QCode.cc

سازمانی ←