# دليل استكشاف الأخطاء وإصلاحها

## أُعدّ المفتاح وما زالت الطلبات تفشل؟ تحقق بهذا الترتيب

تنتظم بقية هذه الصفحة حسب رمز الخطأ؛ إذا كنت **قد أدخلت المفتاح وعناوين URL تمامًا كما هو موثق وما زالت الطلبات تفشل**، فابدأ بمراجعة قائمة التحقق هذه (الاختبار الذاتي عبر curl وقراءة رمز HTTP: [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)، القسم 5):

1. **نفّذ اختبارًا ذاتيًا واحدًا عبر curl أولًا.** فسّر الرمز: `401` = مشكلة في المفتاح؛ `404` = بادئة مسار خاطئة؛ `400` مع `model_not_available_on_endpoint` = بروتوكول خاطئ (ليست مشكلة في المفتاح — راجع البند 4)؛ لا يُنشأ الاتصال مطلقًا = شبكة/وكيل، راجع البند 6؛ `402` مع رمز مثل `*_cost_limit_exceeded` = المسار والمفتاح سليمان، وقد استُهلكت الحصة ببساطة (راجع [رموز الأخطاء](/docs/reference/errors#402-quota-exhausted)).
2. **المتغير الصحيح في الموضع الخاطئ.** يُرسَل `ANTHROPIC_AUTH_TOKEN` ضمن ترويسة `Authorization: Bearer`، ويُرسَل `ANTHROPIC_API_KEY` ضمن `x-api-key` — وإذا وضعت المفتاح في المتغير الخاطئ فلن ترى البوابة بيانات اعتماد صالحة أبدًا. **المتغيرات القديمة في بيئتك تتجاوز الإعدادات الحالية**: نفّذ `env | grep -i anthropic` و`env | grep -i openai` وأزل المخلفات.
3. **شكل Base URL.** عائلة Claude Code: `https://api.qcode.cc/api` (**دون `/v1`**)؛ عملاء OpenAI SDK / العملاء المتوافقون: `https://api.qcode.cc/openai/v1`؛ Codex CLI في ملف إعداداته: `https://api.qcode.cc/openai` مع `wire_api = "responses"`. مقطع واحد زائد أو ناقص = 404.
4. **عدم تطابق البروتوكول / النموذج.** إرسال نموذج Claude إلى نقطة نهاية OpenAI يعيد `model_not_available_on_endpoint` قبل المصادقة — بدّل نقطة النهاية أو النموذج باستخدام المصفوفة في [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) القسم 2.
5. **انحدارات إصدارات العميل (Claude Code):**
   - **2.1.265–2.1.267**: كل طلب يعيد 400 (يُرفض مخطط أداة Artifact) — رقِّ إلى **≥2.1.268** أو عيّن `CLAUDE_CODE_DISABLE_ARTIFACT=1`.
   - **2.1.275**: عندما يشير `ANTHROPIC_BASE_URL` إلى بوابة، يفشل كل طلب بالخطأ `400 … Input tag 'advisor_20260301'` — رقِّ إلى **≥2.1.276**.
   - أخطاء `Unexpected value(s) … anthropic-beta` — عيّن `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.
6. **وكيل النظام مقابل نطاق الوصول.** تعيد `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` توجيه حركة المرور؛ أضف `*.qcode.cc` إلى `NO_PROXY` أو أزل تعيينها مؤقتًا ثم أعد المحاولة.
7. **ما زلت عالقًا**: ابحث عن الطلب على [probe.qcode.cc](https://probe.qcode.cc) باستخدام مفتاحك لترى ما الذي أُرسل فعليًا، ثم **تواصل مع الدعم مع معرّف الطلب** (الدردشة المباشرة أو hi@qcode.cc).

توجد دلالات رموز الأخطاء في [رموز الأخطاء](/docs/reference/errors)؛ وللأسئلة من نوع «هل يمكن لاشتراكي أن يعمل كـ API» راجع [الاشتراكات مقابل مفاتيح API مقابل مفاتيح QCode](/docs/reference/subscription-vs-api-key).

لا تُصَبْ بالذعر إذا واجهت مشكلات أثناء استخدام Claude Code. ينظَّم هذا الدليل وفق تدفق «الفحص الذاتي السريع → استكشاف الأخطاء خطوة بخطوة → الحلول» لمساعدتك على تحديد المشكلات وحلها بكفاءة.
## الفحص الذاتي السريع

عند مواجهتك مشكلات، ابدأ بهذه الفحوص السريعة الثلاثة—يمكن تحديد 80% من المشكلات في هذه الخطوة.

### 1. تحقق من إصدار Claude Code

```bash
claude --version
```

تأكد من أنك تستخدم أحدث إصدار. يصدر Claude Code تحديثات متكررة، وقد أُصلحت مشكلات كثيرة في الإصدارات الأحدث.

**قم بالترقية إلى أحدث إصدار:**

```bash
npm update -g @anthropic-ai/claude-code
```

### 2. شغّل التشخيصات التلقائية

```bash
claude /doctor
```

يفحص الأمر `/doctor` تلقائياً:
- ما إذا كان إصدار Node.js يستوفي المتطلبات (≥ 18)
- ما إذا كان مفتاح API صالحاً
- ما إذا كان اتصال الشبكة طبيعياً
- ما إذا كان ملف التكوين يحتوي على أخطاء صياغة

### 3. تحقق من إصدار Node.js

يتطلب Claude Code الإصدار 18 من Node.js أو أحدث:

```bash
node --version
# Should output v18.x.x or higher
```

إذا كان الإصدار منخفضاً جداً، فيرجى الترقية:

```bash
# Use nvm to manage Node.js versions (recommended)
nvm install 22
nvm use 22

# Or download and install directly
# Visit https://nodejs.org/ to download the LTS version
```

## مشكلات التثبيت

### خطأ صلاحيات npm install

**الأعراض:**

```bash
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
```

**الحل 1: استخدم sudo (سريع لكن غير موصى به للاستخدام طويل الأمد)**

```bash
sudo npm install -g @anthropic-ai/claude-code
```

**الحل 2: غيّر دليل npm العام (موصى به)**

```bash
# Create a user-level global package directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH (write to ~/.bashrc or ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall
npm install -g @anthropic-ai/claude-code
```

**الحل 3: استخدم nvm لإدارة Node.js**

```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js
nvm install 22
nvm use 22

# Node.js installed via nvm doesn't require sudo
npm install -g @anthropic-ai/claude-code
```

### مشكلات الشبكة المؤدية إلى فشل التثبيت

**الأعراض:**

```bash
npm ERR! network request to https://registry.npmjs.org/ failed
npm ERR! code ETIMEDOUT
```

**الحل: استخدم مرآة محلية**

```bash
# Temporarily use the Taobao mirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# Or permanently set the mirror
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
```

إذا كنت تستخدم وكيلاً:

```bash
# Set npm proxy
npm config set proxy http://your-proxy-address:port
npm config set https-proxy http://your-proxy-address:port

# After installation, you can remove the proxy settings
npm config delete proxy
npm config delete https-proxy
```

### سياسة تنفيذ Windows PowerShell

**الأعراض:**

```bash
claude : File C:\Users\xxx\AppData\Roaming\npm\claude.ps1 cannot be loaded
because running scripts is disabled on this system.
```

**الحل:**

```powershell
# Open PowerShell as administrator and run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then run claude again
claude
```

أو استخدم CMD بدلاً من PowerShell:

```cmd
# Run directly in CMD
claude
```
## مشكلات الاتصال

تُعد مشكلات الاتصال أكثر أنواع المشكلات شيوعًا التي يواجهها المستخدمون في الصين.

### خطأ في تنسيق مفتاح API

**تنسيق مفتاح API في QCode.cc:**

```text
cr_xxxxxxxxxxxxxxxx
```

لاحظ أن البادئة هي `cr_`، وليست `sk-ant-` الرسمية الخاصة بـ Anthropic.

**تحقق من إعدادات مفتاح API:**

```bash
# View current environment variable
echo $ANTHROPIC_AUTH_TOKEN

# Correct setup (QCode.cc key)
export ANTHROPIC_AUTH_TOKEN="cr_your-key"
```

**الأخطاء الشائعة:**

| الخطأ | الوصف |
|------|------|
| مسافات قبل المفتاح أو بعده | `cr_ xxx` → `cr_xxx` |
| استُخدم تنسيق المفتاح الرسمي | `sk-ant-xxx` هو مفتاح Anthropic الرسمي، وليس مفتاح QCode.cc |
| اقتُطع المفتاح | تحقق مما إذا كنت قد نسخت المفتاح كاملًا |
| استُخدم مفتاح منتهي الصلاحية | تأكد من حالة المفتاح في لوحة تحكم QCode.cc |

### خطأ في إعداد ANTHROPIC_BASE_URL

عند استخدام خدمة QCode.cc، تحتاج إلى ضبط Base URL بشكل صحيح:

```bash
# QCode.cc's Base URL
export ANTHROPIC_BASE_URL="https://your-service-address"
```

**خطوات استكشاف الأخطاء وإصلاحها:**

```bash
# 1. Check current configuration
echo $ANTHROPIC_BASE_URL

# 2. Confirm URL format is correct
#    - Must start with https://
#    - No trailing slash /
#    - Should not contain paths (like /v1/messages)

# Correct: the Anthropic protocol needs the /api prefix, but no request-path segment
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"

# Wrong: missing https / an extra trailing slash / the path segment spelled out
export ANTHROPIC_BASE_URL="http://api.qcode.cc/api"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/"
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api/v1/messages"
```

### فشل الاتصال بسبب الوكيل/VPN

**الأعراض:**

```text
Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND api.example.com
```

**خطوات استكشاف الأخطاء وإصلاحها:**

```bash
# 1. Check if proxy is correctly set
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# 2. Test network connectivity
curl -v https://your-service-address/health

# 3. If using a proxy, ensure Claude Code can use it
export HTTP_PROXY="http://proxy-address:port"
export HTTPS_PROXY="http://proxy-address:port"

# 4. If you don't need a proxy but have one set, unset it
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY
```

**ملاحظات حول VPN:**

- تأكد من أن VPN لا يعترض طلبات API
- قد تؤثر بعض قواعد التقسيم النفقي في VPN على اتصالات API
- إذا تسبب VPN في مشكلات، فجرّب إضافة نطاق API إلى قواعد الاتصال المباشر

### مشكلات شهادات SSL/TLS

**الأعراض:**

```text
Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
```

**الحلول:**

```bash
# Solution 1: Update system CA certificates
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
brew install ca-certificates

# Solution 2: For corporate network mitm certificates, set Node.js to trust them
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.crt"

# Solution 3: Temporarily skip certificate verification (only for testing, not recommended for long-term use)
export NODE_TLS_REJECT_UNAUTHORIZED=0
```

### اختبار الاتصال

استخدم curl لاختبار الاتصال بـ API مباشرة:

```bash
# Test basic connectivity
curl -s -o /dev/null -w "%{http_code}" \
  https://your-service-address/health

# Test API call (replace with your key and address)
curl https://your-service-address/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_your-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

**النتائج المتوقعة:**
- فحص الحالة يعيد `200`
- استدعاء API يعيد استجابة JSON

**مرجع المشكلات الشائعة:**

| نتيجة curl | السبب المحتمل | الحل |
|-------------|---------------|----------|
| `connection refused` | عنوان الخدمة خاطئ أو الخدمة لا تعمل | تحقق من ANTHROPIC_BASE_URL |
| `connection timeout` | تعذّر الوصول إلى الشبكة أو حجبها جدار الحماية | تحقق من إعدادات الشبكة/الوكيل |
| `401 Unauthorized` | مفتاح API غير صالح | تحقق مما إذا كان المفتاح صحيحًا |
| `403 Forbidden` | المفتاح يفتقر إلى الأذونات | تواصل مع مزوّد الخدمة |
| أخطاء متعلقة بـ SSL | مشكلة في الشهادة | راجع قسم SSL أعلاه |

## مشكلات الأذونات

### أذونات قراءة/كتابة الملفات غير كافية

**الأعراض:**

```text
Error: EACCES: permission denied, open '/path/to/file'
```

**الحلول:**

```bash
# 1. Check file permissions
ls -la /path/to/file

# 2. Ensure current user has read/write permissions
chmod u+rw /path/to/file

# 3. Check directory permissions (Claude needs write permission to create new files)
chmod u+w /path/to/directory

# 4. If file was created by root, change ownership
sudo chown $(whoami) /path/to/file
```

**إعداد أذونات Claude Code:**

يمتلك Claude Code نظام أذونات للتحكم في العمليات التي يمكنه تنفيذها. إذا وجدت أن Claude ممنوع من تنفيذ عملية:

```bash
# View current permission settings
claude /permissions

# Configure allowed directories in settings.json
# ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Read files in /home/user/projects/**",
      "Write files in /home/user/projects/**",
      "Execute bash commands"
    ]
  }
}
```

### رفض عمليات Git

**الأعراض:**

```text
fatal: unable to access 'https://github.com/xxx/xxx.git/':
The requested URL returned error: 403
```

**الحلول:**

```bash
# 1. Check Git configuration
git config --list

# 2. Confirm SSH key or Token configuration
ssh -T git@github.com          # Test SSH connection
gh auth status                  # Test GitHub CLI authentication

# 3. If using HTTPS, check credentials
git config credential.helper    # View credential helper

# 4. Ensure Claude Code is in the correct Git repository
git status                      # Confirm you're in the repository directory
```

### فشل تنفيذ أوامر Bash

قد يحتاج Claude Code إلى تأكيدك عند تنفيذ أوامر bash. إذا استمر رفض أمر ما:

```bash
# View permission configuration
claude /permissions

# If it's a project you trust, you can configure allowed commands in CLAUDE.md
# CLAUDE.md
## Allowed Commands
allowedTools:
  - Bash(npm run *)
  - Bash(pnpm *)
  - Bash(git *)
  - Bash(docker compose *)
```

## مشكلات الأداء

### بطء سرعة الاستجابة

**الأسباب المحتملة والحلول:**

| السبب | طريقة التشخيص | الحل |
|------|------------------|----------|
| زمن استجابة الشبكة | `ping service-address` | افحص الشبكة/الوسيط |
| استخدام نموذج Opus | `/model` للعرض | بدّل إلى Sonnet |
| السياق كبير جدًا | `/cost` لعرض عدد token | `/compact` للضغط |
| حمل مرتفع على الخادم | افحص زمن استجابة HTTP | أعد المحاولة لاحقًا |

**اقتراحات تحسين الشبكة (للمستخدمين في الصين):**

```bash
# Test latency to the server
ping service-address

# If latency exceeds 500ms, consider:
# 1. Check if proxy configuration is optimal
# 2. Try using at different times (avoid peak hours)
# 3. Contact QCode.cc customer service for optimal nodes
```

### تجاوز سعة السياق

**الأعراض:**
- تبدأ ردود Claude في «نسيان» ما قيل سابقًا
- تتدهور جودة الردود بشكل ملحوظ
- يظهر محتوى متكرر أو متناقض

**الحلول:**

```bash
# Solution 1: Compress context (retain key information)
/compact

# Solution 2: Clear completely (if you can start over)
/clear

# Solution 3: Streamline each input
# Don't send large amounts of file content at once
# Use @ to reference files instead of pasting
# Handle one task at a time
```

**تدابير الوقاية:**

- فكّر في استخدام `/compact` بعد إكمال كل مهمة مستقلة
- عند الانتقال إلى موضوعات مختلفة، لا تتردد في استخدام `/clear`
- استخدم `.claudeignore` لاستبعاد الملفات الكبيرة غير ذات الصلة
- استخدم `@` للإشارة بدقة إلى الملفات المطلوبة، ولا تدع Claude يبحث عالميًا

### ارتفاع استخدام الذاكرة

**الأعراض:**
- يصبح النظام بطيئًا
- تستهلك عملية Claude Code قدرًا كبيرًا من الذاكرة

**الحلول:**

```bash
# 1. Check Node.js memory usage
node -e "console.log(process.memoryUsage())"

# 2. Upgrade Node.js to the latest LTS version
nvm install 22
nvm use 22

# 3. If the problem persists, limit Node.js maximum memory
export NODE_OPTIONS="--max-old-space-size=4096"

# 4. Restart Claude Code
# Exit current session and restart
exit
claude
```
## مرجع رموز الأخطاء الشائعة

| رمز الخطأ | المعنى | السبب | الحل |
|-----------|---------|-------|----------|
| **400** | طلب غير صالح | تنسيق الطلب غير صحيح | تحقق من وجود أحرف غير صالحة في الإدخال؛ وحدّث Claude Code إلى أحدث إصدار |
| **401** | غير مصرح | مفتاح API غير صالح أو منتهي الصلاحية | تحقق من إعداد `ANTHROPIC_AUTH_TOKEN`؛ وتأكد من أن المفتاح لم تنته صلاحيته |
| **402** | الدفع مطلوب | الحصة مستنفدة، أو الخدمة ترفض مؤقتًا | يعني `error.type` = `insufficient_quota` أن الحصة مستنفدة (تحقق من `code`: تُعاد الحصة اليومية عند 00:00 بتوقيت بكين، وتتوفر باقات التعزيز)؛ وإلا فبدّل النموذج أو نطاق نقطة النهاية؛ راجع [رموز الأخطاء](/docs/reference/errors#402-quota-exhausted) |
| **403** | محظور | لا توجد أذونات | تأكد من أن المفتاح يملك أذونات الوصول إلى النموذج المقابل |
| **404** | غير موجود | النموذج أو المسار غير موجود | تحقق من صحة `ANTHROPIC_BASE_URL` واسم النموذج |
| **429** | طلبات كثيرة جدًا | الطلبات متكررة جدًا | انتظر 30-60 ثانية ثم أعد المحاولة؛ وقلّل الطلبات المتزامنة |
| **500** | خطأ داخلي في الخادم | خطأ داخلي في الخادم | أعد المحاولة لاحقًا؛ وإذا استمر فتواصل مع خدمة العملاء |
| **502** | بوابة غير صالحة | خدمة الخلفية غير متاحة | أعد المحاولة لاحقًا؛ وتحقق من إعلانات الخدمة |
| **503** | الخدمة غير متاحة | الخدمة محمّلة فوق طاقتها مؤقتًا | انتظر بضع دقائق ثم أعد المحاولة |
| **529** | تحميل زائد على API | تحميل زائد على Claude API | يرجع ذلك إلى ارتفاع الحمل على خوادم Anthropic؛ انتظر ثم أعد المحاولة |

### 402 عند استنفاد الحصة: ما يجب فحصه بالترتيب

إذا كانت الاستجابة 402 وكان `error.type` هو `insufficient_quota`، فاتبع هذه الخطوات بهذا الترتيب:

1. **اقرأ `code`** لمعرفة الحصة التي استُنفدت (التفاصيل في [مرجع الأخطاء](/docs/reference/errors#402-quota-exhausted)).
2. **`daily_cost_limit_exceeded` (الحصة اليومية للخطة الشخصية)**: انتظر إعادة التعيين التلقائي عند 00:00 بتوقيت بكين، أو اشترِ باقة التعزيز من لوحة التحكم.
3. **`total_cost_limit_exceeded` (الحصة الإجمالية)**: تحقق من بطاقة **مفتاح الدفع حسب الاستخدام** في لوحة التحكم لمعرفة الحصة المتبقية وتاريخ انتهاء الصلاحية، و**جدّد** عند استنفادها (تتراكم عمليات التجديد على المفتاح نفسه، والقواعد في [باقات الدفع حسب الاستخدام](/docs/reference/payg-packs))؛ وللاطلاع على الحصة الشهرية لـ Ultimate راجع [الأسئلة الشائعة](/docs/reference/faq). القيمة بين القوسين في الرسالة هي الحد التراكمي، وليس المتبقي.
4. **الحد الأسبوعي لنماذج Claude**: يُعاد تعيينه تلقائيًا وفق الدورة المُعدّة للمفتاح؛ ويمكنك أيضًا التبديل إلى نموذج آخر في الأثناء.
5. **ظهور 401** بدلًا من 402: انتهت صلاحية المفتاح. يؤدي تجديد الباقة إلى استعادة المفتاح نفسه (قد يستغرق ذلك حتى نحو 5 دقائق على العُقد الخارجية).

لا يزول خطأ 402 بإعادة الإرسال، لذلك لا تكتب حلقة إعادة محاولة.

### تفاصيل 429: تقييد معدل الطلبات

يُعد 429 الخطأ الأكثر شيوعًا، ويستحق شرحًا مفصلًا:

**المحفّزات:**

1. **ارتفاع وتيرة الطلبات**: إرسال عدد كبير جدًا من الطلبات في الثانية
2. **استهلاك tokens سريع جدًا**: استهلاك عدد كبير من tokens في وقت قصير
3. **كثرة الجلسات المتزامنة**: تشغيل عدة نسخ من Claude Code في الوقت نفسه

> **استنفاد الحصة ليس خطأ 429**: عند استنفاد الحصة اليومية أو الإجمالية أو الأسبوعية، تكون الاستجابة **402** (`insufficient_quota`) — راجع [رموز الأخطاء](/docs/reference/errors#402-quota-exhausted).

**الاستجابة المتدرجة:**

```bash
# Occasional 429
# → Wait 30 seconds for automatic retry, Claude Code has built-in retry logic

# Frequent 429
# → Reduce request frequency
# → Use /compact to reduce context size
# → Avoid running multiple Claude Code instances simultaneously

# Persistent 429
# → Check how many sessions you are running in parallel
# → Log in to QCode.cc Dashboard to view usage
# → A used-up quota returns 402, not 429 — see the error code reference
```

### تفاصيل 529: تحميل زائد على API

529 رمز خطأ خاص بـ Anthropic يشير إلى تحميل زائد على خوادم Claude API:

```text
Error: 529 API Overloaded
The API is temporarily overloaded. Please try again later.
```

**إجراءات الاستجابة:**

- هذه ليست مشكلتك؛ إنها حالة مؤقتة على خادم Anthropic
- تستمر عادةً من بضع دقائق إلى بضع عشرات من الدقائق
- انتظر 1-2 دقيقة ثم أعد المحاولة
- إذا استمرت، يمكنك التبديل مؤقتًا إلى نموذج آخر (مثل سلسلة GPT)
- تابع [حالة Anthropic](https://status.anthropic.com/) لمعرفة حالة الخدمة
## مشكلات شائعة أخرى

### لا استجابة بعد بدء Claude Code

```bash
# 1. Check if properly installed
which claude
npm list -g @anthropic-ai/claude-code

# 2. View detailed error information
claude --debug

# 3. Try clearing cache and restarting
rm -rf ~/.claude/cache
claude
```

### عدم تفعيل CLAUDE.md

```bash
# 1. Confirm file location is correct
ls -la CLAUDE.md                # Project root directory
ls -la .claude/CLAUDE.md        # Project private configuration
ls -la ~/.claude/CLAUDE.md      # Global configuration

# 2. Confirm file encoding is UTF-8
file CLAUDE.md
# Should display: CLAUDE.md: UTF-8 Unicode text

# 3. Confirm no syntax errors (although it's Markdown, some special characters may cause parsing issues)
# Avoid using special markers other than ``` in CLAUDE.md

# 4. Restart Claude Code for configuration to take effect
# Exit and re-enter
```

### ظهور الأحرف الصينية كنص مشوّه

```bash
# 1. Check terminal encoding settings
echo $LANG
# Should include UTF-8, for example en_US.UTF-8 or zh_CN.UTF-8

# 2. Set correct encoding
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

# 3. Confirm terminal supports UTF-8
# macOS Terminal / iTerm2 supports by default
# Windows Terminal supports by default
# Windows CMD requires: chcp 65001
```

### تعارضات Git التي تؤدي إلى فشل عمليات Claude

```bash
# 1. First resolve Git conflicts
git status     # View conflicting files
git diff       # View conflict content

# 2. Let Claude help resolve conflicts
> "View the current git conflict files and help me resolve these conflicts. Keep changes from both sides."

# 3. Continue after resolution
git add .
git commit -m "resolve merge conflicts"
```

### مشكلات Docker ذات الصلة (للمستخدمين المتقدمين)

إذا كنت تستخدم Claude Code داخل حاوية Docker:

```bash
# Ensure container has Node.js 22+
docker run -it node:22-slim bash

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Pass necessary environment variables
docker run -it \
  -e ANTHROPIC_AUTH_TOKEN="cr_your-key" \
  -e ANTHROPIC_BASE_URL="https://your-service-address" \
  -v $(pwd):/workspace \
  -w /workspace \
  node:22-slim claude
```

## ملخص مسار استكشاف الأخطاء وإصلاحها

عند مواجهة مشكلات، اتبع هذا المسار في استكشاف الأخطاء وإصلاحها:

```text
1. Quick Self-Check
   ├── claude --version (is version latest)
   ├── claude /doctor (automatic diagnostics)
   └── node --version (Node.js ≥ 18)

2. Network Connectivity
   ├── curl test API address
   ├── Check proxy/VPN settings
   └── Check DNS resolution

3. Authentication Configuration
   ├── Is ANTHROPIC_AUTH_TOKEN format correct
   ├── Is ANTHROPIC_BASE_URL correct
   └── Is key expired

4. Permission Check
   ├── File system permissions
   ├── Git permissions
   └── Claude Code permission configuration

5. Performance Optimization
   ├── /compact to compress context
   ├── /model to switch to appropriate model
   └── .claudeignore to exclude large files

6. If none of the above solves it → Get Help
```

## الحصول على الدعم

إذا لم تحل أي من الطرق السابقة مشكلتك، يمكنك الحصول على الدعم عبر هذه القنوات:

### خدمة عملاء QCode.cc عبر الإنترنت

انقر على أيقونة خدمة العملاء عبر الإنترنت في الزاوية السفلية اليمنى من موقع [QCode.cc](https://qcode.cc). خلال ساعات العمل، يمكنك عادةً الحصول على رد خلال بضع دقائق.

**عند طرح الأسئلة، يُرجى تقديم:**
- إصدار Claude Code (ناتج `claude --version`)
- نظام التشغيل وإصداره
- رسالة الخطأ الكاملة
- الحلول التي جرّبتها

### مشكلات GitHub

Claude Code مشروع مفتوح المصدر، ويمكنك إرسال المشكلات على GitHub:

- **عنوان المستودع**: [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)
- ابحث في المشكلات الحالية لمعرفة ما إذا كان أي شخص قد واجه المشكلة نفسها
- عند إرسال مشكلة جديدة، صِفها باللغة الإنجليزية (يسهل الحصول على رد رسمي)

### موارد المجتمع

- **الوثائق الرسمية لـ Claude Code**: [docs.anthropic.com](https://docs.anthropic.com)
- **حالة خدمة Anthropic**: [status.anthropic.com](https://status.anthropic.com)
- **وثائق مستخدم QCode.cc**: [docs.qcode.cc](https://docs.qcode.cc)

> لا تخف من المشكلات؛ فمعظمها لها حلول بسيطة. باتباع مسار استكشاف الأخطاء وإصلاحها في هذا الدليل، يمكنك عادةً حل المشكلات خلال بضع دقائق.