# آموزش Claude Code: نصب و اجرا (2026)

> **آخرین بازبینی**: 2026-10-20 · 📄 بر پایه مستندات رسمی و qcode.cc (راه‌اندازی Claude Code؛ صفحه نصب یک‌کلیکی QCode؛ بازبینی‌شده در 2026-10-20)

**کوتاه‌ترین مسیر**

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

```powershell
# 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

| به‌روزرسانی | چه کاری انجام می‌دهد |
|------|------|
| **Plan Mode** | ابتدا پژوهش و تحلیل، سپس ارائه یک برنامه — اشتباهات کمتر |
| **Agent Teams** | چند عامل که به‌صورت موازی کار می‌کنند و از طریق git worktree از هم جدا می‌شوند |
| **Voice Mode** | تعامل صوتی — کلید فاصله را نگه دارید و صحبت کنید |
| **Computer Use** | دسکتاپ، مرورگر و ابزارهای توسعه‌دهنده را کنترل می‌کند |
| **سیستم Hooks** | 17 رویداد چرخه عمر برای خودکارسازی جریان‌های کاری |
| **پروتکل MCP** | ابزارها و سرویس‌های خارجی را متصل می‌کند |
| **Skills** | ماژول‌های دانش — قالب‌های جریان کاری قابل اشتراک‌گذاری |
| **Extended Thinking** | پیش از پاسخ به پرسش‌های دشوار، در خلوت عمیق استدلال می‌کند |
| **Opus 5 / Sonnet 5** | پرچمدار کنونی و پیش‌فرض روزمره (4.8 / 4.6 هنوز عرضه می‌شوند) |
| **1M Context Beta** | `claude-sonnet-5` / `claude-opus-5` و مدل‌های دیگر از پنجره زمینه 1M توکن پشتیبانی می‌کنند |

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

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

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

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

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

| نیازمندی | جزئیات |
|------|------|
| سیستم‌عامل | macOS 12+، Ubuntu 20.04+، Windows 10+ (WSL2) |
| Node.js | نسخه 22 یا جدیدتر برای بسته npm؛ برای Native Install لازم نیست |
| Git | نسخه 2.x یا جدیدتر |
| فضای دیسک | حدود 200MB |

Claude Code به‌صورت بومی روی Windows یا داخل WSL اجرا می‌شود؛ نصب‌کننده بومی زیر به Node.js نیاز ندارد؛ بسته npm به Node.js 22 یا جدیدتر نیاز دارد (مستندات رسمی، بررسی‌شده در 2026-10-20).

### نصب Claude Code

روش رسمی توصیه‌شده در حال حاضر **Native Install** است (بررسی‌شده در 2026-10-20):

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

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

```bash
# Homebrew
brew install --cask claude-code
```

npm همچنان کار می‌کند:

```bash
# 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

متغیرهای محیطی را در ترمینال خود تنظیم کنید:

```bash
# 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](https://qcode.cc/dashboard)؛ با `cr_` شروع می‌شود.

> **انتخاب نقطه پایانی**: پیش‌فرض `https://api.qcode.cc/api` است (Route 53 جهانی به‌طور خودکار نزدیک‌ترین نود را انتخاب می‌کند). کاربران در چین سرزمین اصلی باید `asia.qcode.cc` را ترجیح دهند (نود آسیا، نزدیک‌ترین از میان کره / تایوان / هنگ‌کنگ، با کم‌ترین تأخیر). دامنه‌های دیگر (`us` / `asia`) و قواعد BASE_URL در [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) پوشش داده شده‌اند.

پیکربندی را اعمال کنید:

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

### بررسی نصب

```bash
# 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
# Bash
claude completion bash >> ~/.bashrc

# Zsh
claude completion zsh >> ~/.zshrc

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

---
## 3. اولین استفاده

### شروع

آن را در هر دایرکتوری پروژه اجرا کنید:

```bash
cd ~/my-project
claude
```

Claude Code ساختار پروژه را به‌طور خودکار بررسی می‌کند و وارد حالت تعاملی می‌شود.

### بررسی حداقلی پس از اجرا

```bash
# 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 فعال هستند.

### خواندن رابط کاربری

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

> _
```

به زبان ساده تایپ کنید — Claude متوجه می‌شود و اقدام می‌کند.

### اولین وظیفه: درک پروژه

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

Claude به‌طور خودکار:
1. فایل‌های `package.json`، `README.md` و ساختار دایرکتوری را می‌خواند
2. فایل‌های کلیدی منبع را به‌سرعت مرور می‌کند
3. یک تحلیل ساختاریافته از معماری تولید می‌کند

### درخواست‌های مجوز

وقتی Claude می‌خواهد اقدامی انجام دهد، از شما تأیید می‌خواهد:

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

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

- **y**: این بار اجازه داده شود
- **n**: رد شود
- **a**: برای ادامه این نشست، همیشه این نوع اقدام را مجاز کنید (برای توسعه روزمره مفید است)

### حالت‌های رایج مجوز

| حالت | چه کاری انجام می‌دهد | چه زمانی استفاده شود |
|------|------|---------|
| `auto` (پیش‌فرض از 2.1.283) | یک طبقه‌بند اقداماتی را که به تأیید نیاز دارند بررسی می‌کند و اقدامات خطرناک را مسدود می‌کند | توسعه روزمره، وظایف طولانی |
| `default` (دستی) | برای هر اقدامی که به تأیید نیاز دارد، درخواست تأیید می‌کند | بار اول، پروژه‌های حساس |
| `--permission-mode dontAsk` + `--allowedTools` | فقط ابزارهای ازپیش‌تأییدشده را اجرا می‌کند و بقیه را رد می‌کند | CI/CD، اسکریپت‌ها |
| `--dangerously-skip-permissions` | همه تأییدها را نادیده می‌گیرد | فقط کانتینرها/ماشین‌های مجازی ایزوله |

---

## 4. قابلیت‌های اصلی

### 4.1 Plan Mode

Plan Mode باعث می‌شود Claude ابتدا تحقیق و تحلیل کند و تنها پس از آن طرحی پیشنهاد دهد. این حالت برای وظایف پیچیده مناسب است.

```bash
# 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 آن را اجرا می‌کند

**مثال**:

```text
> /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](/docs/usage/adaptive-thinking) مراجعه کنید. روی مسائل سخت، ابتدا به‌صورت خصوصی و عمیق استدلال می‌کند.

```text
> 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 می‌تواند برای وظایف مشخص، زیرعامل‌های تخصصی ایجاد کند:

```text
> 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 دستورهای کلیدی

| دستور | چه کاری انجام می‌دهد | مثال |
|------|------|------|
| `/model` | تغییر مدل | `/model opus` |
| `/plan` | ورود به Plan Mode | `/plan` |
| `/compact` | فشرده‌سازی زمینه | `/compact` |
| `/cost` | نمایش هزینه فعلی | `/cost` |
| `/clear` | پاک‌کردن زمینه | `/clear` |
| `/init` | تولید CLAUDE.md | `/init` |
| `/review` | بازبینی کد | `/review` |
| `/help` | راهنما | `/help` |
| `Esc` | لغو اقدام فعلی | |
| `Ctrl+C` | قطع پاسخ | |

### 4.5 مدیریت زمینه

Claude Code یک پنجره زمینه 200K توکنی دارد. نشست‌های طولانی نیاز به مدیریت دارند:

```bash
# 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` پروژه را می‌خواند تا معماری، استانداردهای کدنویسی و قراردادهای محلی را یاد بگیرد. بدون آن، در هر جلسه باید پروژه را دوباره توضیح دهید.

### ایجاد سریع آن

```bash
# Claude analyses the project and generates the file
/init
```

### سلسله‌مراتب فایل

| مکان | محدوده | Git |
|------|---------|---------|
| `~/.claude/CLAUDE.md` | سراسری (همه پروژه‌ها) | ردیابی نمی‌شود |
| `project root/CLAUDE.md` | این پروژه | کامیت در Git |
| `.claude/CLAUDE.md` | این پروژه (خصوصی) | به .gitignore اضافه کنید |
| `subdirectory/CLAUDE.md` | فقط همان زیرپوشه | در صورت نیاز |

### قالب عملی: پروژه React + TypeScript

```markdown
# 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](/docs/usage/claude-md) را ببینید.

---

## 6. انتخاب مدل

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

صورت‌حساب به‌ازای هر توکن است؛ نرخ هر مدل در [qcode.cc/models](https://qcode.cc/models) فهرست شده است (بررسی‌شده در 2026-10-20). مدل‌های 4.x همچنان به فروش می‌رسند، فقط دیگر پیش‌فرض نیستند.

| | Opus 5 | Sonnet 5 | Haiku 4.5 |
|--------|----------|------------|-----------|
| **جایگاه** | پرچمدار کنونی | پیش‌فرض روزمره | سبک و سریع |
| **استدلال** | بسیار قوی | قوی | کافی |
| **کیفیت کد** | بسیار بالا | بالا | متوسط |
| **سرعت پاسخ** | کندتر | متوسط | سریع |
| **پنجره زمینه** | 1M / 128K | 1M / 128K | 200K |

### تغییر مدل

```bash
# 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
```

### توصیه‌ها بر اساس سناریو

| سناریو | توصیه‌شده | دلیل |
|------|---------|------|
| طراحی معماری | **Opus** | استدلال عمیق، حفظ دید کلی |
| کدنویسی روزمره | **Sonnet** | تعادل توانایی و سرعت |
| رفع باگ | **Sonnet** | به‌اندازه کافی خوب و سریع |
| اشکال‌زدایی دشوار | **Opus** | Extended Thinking |
| قالب‌بندی کد | **Haiku** | وظایف سبک |
| بازبینی PR | **Sonnet** | تعادل سرعت و کیفیت |
| بازآرایی‌های بزرگ | **Opus** | نیازمند درک کل پروژه |
| نوشتن مستندات | **Sonnet** | به‌اندازه کافی خوب |

### راهبرد ترکیبی (توصیه‌شده)

```text
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
```

می‌توانید در هر نقطه از گفتگو مدل را تغییر دهید:

```bash
# 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` پیکربندی کنید:

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

> راهنمای کامل: [Hooks System](/docs/advanced/hooks).

### سرورهای MCP

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

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

### Skills

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

```bash
# 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

فراخوانی اسکریپتی با نادیده گرفتن همه ویژگی‌های تعاملی:

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

---

## 8. مثال‌های عملی

### مثال 1: درک یک پایگاه کد جدید

```bash
cd ~/unfamiliar-project
claude
```

```text
> 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

```text
> /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: اشکال‌زدایی یک باگ دشوار

```text
/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: بازآرایی دسته‌ای

```text
> 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: نوشتن یک مجموعه تست کامل

```text
> 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

```bash
# 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](/docs/advanced/headless).

---
## 9. Claude Code و Codex در کنار هم

Claude Code و OpenAI Codex CLI دو قوی‌ترین ابزار کدنویسی با هوش مصنوعی در سال 2026 هستند و هر کدام نقاط قوت خودشان را دارند.

**بهترین ترکیب**: Claude Code برنامه‌ریزی و بازبینی می‌کند، Codex اجرا می‌کند و کارهای حجیم را انجام می‌دهد.

```bash
# 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](/docs/getting-started/codex-vs-claude-code).
> راهنمای Codex: [آموزش کامل Codex](/docs/ide/codex).

---

> **به‌صورت تیمی کار می‌کنید؟** برای تیم‌های سه نفره و بیشتر [پلن تیمی](https://qcode.cc/enterprise) را پیشنهاد می‌کنیم — دامنه اختصاصی `e-xxx.qcode.cc`، مدیریت کلیدهای فرعی API، تضمین سرویس و انتقال سازمانی. [راهنمای پلن تیمی](/docs/reference/enterprise-guide) را ببینید.

## 10. پرسش‌های متداول

### نصب شکست می‌خورد

**پرسش: `npm install -g` خطای دسترسی می‌دهد**

```bash
# 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
```

### مشکلات شبکه

**پرسش: اتصال با خطای مهلت زمانی مواجه می‌شود یا رد می‌شود**

```bash
# 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** بسپارید (سبک و سریع)
- [راهنمای بهینه‌سازی هزینه](/docs/usage/cost-optimization) را ببینید

### Claude پروژه را نمی‌فهمد

**پرسش: Claude مدام ساختار یا قواعد پروژه را اشتباه می‌فهمد**

یک فایل `CLAUDE.md` بسازید (فصل 5 را ببینید) و پیشینه پروژه، قواعد و دستورهای رایج را در آن بنویسید. Claude در هر شروع به‌طور خودکار آن را می‌خواند.

### تفاوت آن با ابزارهای دیگر

**پرسش: Claude Code چه تفاوتی با Cursor / Copilot دارد؟**

| ابزار | نوع | ویژگی |
|------|------|------|
| **Claude Code** | عامل CLI | خودکار برنامه‌ریزی و اجرا می‌کند، کل پروژه را درک می‌کند |
| **Cursor** | IDE | یکپارچگی عمیق با ویرایشگر، تکمیل در زمان واقعی |
| **Copilot** | افزونه IDE | تکمیل در سطح خط، پیشنهادهای ساده |

Claude Code یک دستیار در سطح عامل است (می‌تواند کارهای پیچیده را به‌تنهایی کامل کند)، نه ابزاری برای تکمیل در سطح خط. این دو خوب با هم کار می‌کنند: Cursor برای ویرایش و تکمیل در زمان واقعی، Claude Code برای برنامه‌ریزی و اجرای کارهای پیچیده.

> **توجه**: همان کلید `cr_` در QCode.cc با Claude Code، Codex CLI و طیف گسترده‌ای از IDEها / CLIها / اپلیکیشن‌های دسکتاپ از جمله Cursor کار می‌کند. برای Cursor (Base URL سفارشی + کلید API) [یکپارچه‌سازی ویرایشگر Cursor](/docs/ide/cursor) را ببینید؛ جدول پروتکل‌ها و فهرست کامل در [نمای کلی سازگاری ابزارها](/docs/ide/tool-compatibility) آمده است.

---

## مستندات مرتبط

- [راهنمای نصب](/docs/getting-started/installation) — مراحل دقیق نصب
- [پیکربندی CLAUDE.md](/docs/usage/claude-md) — راهنمای کامل پیکربندی پروژه
- [سیستم Hooks](/docs/advanced/hooks) — جزئیات Hooks خودکارسازی
- [خودکارسازی و CI/CD](/docs/advanced/headless) — استفاده از حالت headless
- [راهنمای انتخاب مدل](/docs/usage/model-selection) — مقایسه دقیق مدل‌ها
- [بهینه‌سازی هزینه](/docs/usage/cost-optimization) — تکنیک‌های کنترل هزینه
- [Codex در برابر Claude Code](/docs/getting-started/codex-vs-claude-code) — مقایسه این دو ابزار
- [آموزش کامل Codex](/docs/ide/codex) — راهنمای کامل Codex
- [پلن‌ها و قیمت‌گذاری](https://qcode.cc/pricing) — پلن‌های QCode.cc