# سكربت الإعداد بنقرة واحدة

انتقل من الصفر إلى العمل بأمر واحد: يختار السكربت أسرع نقطة نهاية عبر اختبار زمن الاستجابة، ويطلب منك مفتاح API، ويكتب الإعدادات، ويثبّت Node.js وCLI عند الحاجة، ثم يرسل طلبًا مصغّرًا للتحقق من الاتصال. **ابدأ باختيار نظام التشغيل الخاص بك**:

> 📖 قبل التشغيل، احصل على مفتاح API (يبدأ بـ `cr_`) من [لوحة التحكم في QCode.cc](https://qcode.cc/dashboard)؛ سيطالبك السكربت بلصقه (لن يظهر الإدخال).
> يعمل المفتاح بالطريقة نفسها أيًّا كان الخيار الذي تختاره. لم تختر بعد؟ راجع [كيفية اختيار الخطة](/docs/getting-started/choose-a-plan)، ثم احصل على مفتاحك من لوحة التحكم.

هل تشغّل وكلاء على خادم سحابي؟ تعرض صفحة الخادم الأمر نفسه؛ وما يأتي بعده — إعداد المفتاح وإبقاء المهام حيّة بعد انقطاع الاتصال — موجود في [تشغيل الوكلاء على خادم سحابي](/docs/usage/cloud-server-agents).

## لغة الواجهة

تتبع السكربتات لغة نظامك وتنتقل تلقائيًا بين **الإنجليزية** و**الصينية**. لفرض إحداهما صراحةً:

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

```powershell
# Windows PowerShell
$env:QCODE_LANG='zh'; irm https://qcode.cc/install/claude-code.ps1 | iex
```

الصينية هي الافتراضية عندما تكون لغة نظامك الصينية؛ والأوامر العادية أعلاه غير متأثرة بذلك. وينطبق الشيء نفسه على `codex`.

## 🍎 macOS / 🐧 Linux

افتح الطرفية والصق الأمر (لا حاجة إلى sudo):

### Claude Code

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

### Codex

```bash
curl -fsSL https://qcode.cc/install/codex.sh | bash
```

تُكتب الإعدادات في ملف إعدادات الصدفة (كتلة مُدارة في `~/.zshrc` / `~/.bashrc`) أو في `~/.codex/`؛ وإذا كان Node.js غير مثبّت، فيُثبَّت في دليل المنزل عبر nvm.

## 🪟 Windows

**لا تحتاج سوى إلى PowerShell الأصلي — لا WSL ولا صلاحيات مدير.** افتح Windows Terminal أو PowerShell والصق:

### Claude Code

```powershell
irm https://qcode.cc/install/claude-code.ps1 | iex
```

### Codex

```powershell
irm https://qcode.cc/install/codex.ps1 | iex
```

### لا يتوفر `irm`، أو مُنع الأمر بواسطة سياسة التنفيذ؟

تخفّف السكربتات سياسة التنفيذ **للتشغيل الحالي فقط** (دون المساس بإعدادات مستوى المستخدم ومستوى الجهاز)، وتفضّل `npm.cmd` على `npm.ps1` المقيّد بالسياسة. للحالات المتبقية:

**1. داخل CMD (موجه الأوامر)، أو إذا ظهرت لك الرسالة «irm is not recognized»**

`irm` أمر خاص بـ PowerShell وغير موجود في CMD. هذا الأمر يعمل في كليهما:

```
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://qcode.cc/install/claude-code.ps1 | iex"
```

**2. لتشغيله بالنقر المزدوج، أو إذا مُنع `iex` بواسطة السياسة**

نزّل ملف `.cmd` التمهيدي، ثم انقر عليه نقرًا مزدوجًا أو شغّله من CMD:

```
curl -fsSL https://qcode.cc/install/claude-code.cmd -o "%TEMP%\qcode.cmd" && "%TEMP%\qcode.cmd"
```

يأتي Windows 10 1803+ مع `curl.exe`. يستخدم ملف `.cmd` الإصدار 7 من PowerShell عند توفره، ويفرض TLS 1.2، ويُبقي النافذة مفتوحة في النهاية كي لا تمرّ النقرة المزدوجة سريعًا. لواجهة بالصينية: `"%TEMP%\qcode.cmd" zh`. ولـ Codex، استبدل `claude-code` بـ `codex`.

**3. ليعمل `claude` / `codex` دون حجب في جلسات PowerShell المستقبلية أيضًا**

التخفيف أعلاه يغطي الجلسة الحالية فقط. شغّل هذا الأمر مرة واحدة — **لا حاجة إلى صلاحيات مدير**، فهو يؤثر في حسابك فقط:

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

ملاحظات خاصة بـ Windows:

- تُكتب الإعدادات في **متغيرات البيئة على مستوى المستخدم** (يكتب Codex في `%USERPROFILE%\.codex\`)؛ وتُنشأ نسخة احتياطية تلقائيًا من القيم السابقة في `%USERPROFILE%\.qcode\`
- إذا كان Node.js غير مثبّت، يُثبَّت إصدار LTS عبر winget؛ وبدون winget ستحصل على تعليمات التثبيت اليدوي من [nodejs.org](https://nodejs.org/)
- بعد اكتمال الإعداد، تلتقط نوافذ PowerShell / الطرفية **المفتوحة حديثًا** الإعدادات تلقائيًا؛ أما المحررات مثل VS Code فتحتاج إلى إعادة تشغيل واحدة
- إذا مُنع السكربت بواسطة سياسة التنفيذ، فشغّل `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` أولًا ثم أعد المحاولة
## Codex: تطبيق سطح المكتب أم CLI

يسألك `codex.sh` / `codex.ps1` أولًا عن العميل الذي تعتزم استخدامه:

1. **تطبيق Codex لسطح المكتب** (الافتراضي، اضغط Enter فقط) — يكتب ملفات الإعداد فقط؛ **لا يتم فحص Node.js
   وCLI ولا تثبيتهما**
2. **Codex CLI** — ينطبق على التطبيق أيضًا؛ ويثبّت Node.js وCodex CLI عند الحاجة

إذا كنت تستخدم تطبيق سطح المكتب فقط، فاختر 1 ولن يُمس Node إطلاقًا. أعد تشغيل السكربت واختر 2
عندما تريد CLI لاحقًا. غير تفاعلي: `--target app` / `--target cli`
(Windows: `-Target app` / `-Target cli`).

> ℹ️ إذا كان `~/.codex/config.toml` موجودًا بالفعل، فإن السكربت **يحدّث فقط** `model_provider` / `model` /
> `review_model` / `model_reasoning_effort` وجدول `[model_providers.qcode]`. تُحفظ خوادم MCP وملفات التعريف
> و`approval_policy` والإعدادات الأخرى لديك؛ وتُنسخ النسخة الأصلية احتياطيًا باسم `.bak.<timestamp>` في
> الدليل نفسه أولًا. لا يُستبدل بالكامل إلا ملف تالف لا يمكن دمجه بأمان، ويذكر
> السكربت ذلك. ثمة إعداد `profile = …` على المستوى الأعلى (لم يعد مدعومًا في Codex الحالي، الذي يرفض تحميله)
> يُعلَّق؛ للاستمرار في استخدام ملف التعريف ذلك، انقل جدول `[profiles.<name>]` إلى `~/.codex/<name>.config.toml`،
> واحذف الجدول الأصلي، ثم شغّل `codex --profile <name>`. إذا كان Codex CLI مثبتًا، فإن السكربت أيضًا يجعل
> Codex يحمّل الإعداد مرة واحدة ويخبرك إن تعذّر ذلك.
> يُعاد تسمية جدول `crs` الذي كتبته نسخة أقدم من السكربت إلى `qcode` تلقائيًا عند تشغيل السكربت مرة أخرى.

## ماذا يفعل السكربت

1. **اختيار نقطة النهاية وفق زمن الاستجابة** — يرسل طلبًا خفيفًا واحدًا إلى كل نقطة من نقاط النهاية الثلاث (api / asia / us) ويوصي بالأسرع (يمكنك تجاوز هذا الاختيار)
2. **كتابة الإعداد** — Claude Code: كتلة shell مُدارة على macOS/Linux، ومتغيرات بيئة على مستوى المستخدم في Windows؛ Codex: `~/.codex/config.toml` + `auth.json` (يُختار النموذج الافتراضي تفاعليًا، ويُوصى بـ `gpt-6.1-sol`)
3. **تثبيت البيئة** (قابل للتخطي) — يتحقق من Node.js (≥ 22 لسكربت Claude Code، و≥ 20 لسكربت Codex)، ويثبّت إصدار LTS عبر nvm (macOS/Linux) أو winget (Windows) إذا كان مفقودًا أو أقدم، ثم يثبّت CLI باستخدام `npm install -g`؛ ويبقى كل شيء في دليل المستخدم لديك
4. **التحقق من الاتصال** — يرسل طلبًا بالحد الأدنى باستخدام مفتاحك، وعند الفشل يقدّم إرشادات موجّهة لاستكشاف الأخطاء وإصلاحها بناءً على رمز حالة HTTP
5. **النسخ الاحتياطي قبل الكتابة** — يُنسخ كل ملف معدّل احتياطيًا باسم `.bak.<timestamp>` أولًا؛ وفي Windows، تُنسخ متغيرات البيئة السابقة احتياطيًا إلى `%USERPROFILE%\.qcode\`
6. **تنقية المفتاح** — تُزال تلقائيًا علامات الاقتباس المحيطة والمسافات البيضاء وعلامات الترقيم كاملة العرض التي تُلصق مع المفتاح؛ ويُرفض المفتاح الذي يحتوي على أحرف غير صالحة في وسطه رفضًا قاطعًا بدلًا من كتابته في إعدادك
## الوضع غير التفاعلي (CI / بدون prompts)

macOS / Linux:

```bash
curl -fsSL https://qcode.cc/install/claude-code.sh | bash -s -- --key cr_xxx --yes
```

| الخيار | الوصف |
|------|------|
| `--key <cr_...>` | مفتاح API؛ عند توفيره، يتخطى prompt التفاعلي |
| `--domain <api\|asia\|us>` | تثبيت نقطة النهاية مع تخطي اختبار زمن الاستجابة |
| `--model <id>` | Codex: تعيين النموذج الافتراضي مع تخطي أداة الاختيار؛ Claude Code: تثبيت النموذج الافتراضي (يكتب `ANTHROPIC_MODEL`) — احذفه للإبقاء على النموذج الافتراضي لـ Claude Code، الذي يتبع ترقياته |
| `--lang <zh\|en>` | لغة الواجهة؛ تتبع لغة النظام افتراضيًا |
| `--target <app\|cli>` | (codex فقط) الإعداد فقط / تثبيت CLI أيضًا؛ يسأل تفاعليًا افتراضيًا |
| `--yes` / `-y` | قبول الافتراضي في كل تأكيد |
| `--no-install` | كتابة الإعدادات فقط، دون تثبيت Node / CLI |
| `--no-verify` | تخطي التحقق من الاتصال |
| `--dry-run` | طباعة ما سيتم كتابته وتثبيته والتحقق منه؛ دون كتابة أي ملفات، أو تثبيت أي شيء، أو إرسال أي طلب تحقق |
| `--uninstall` | إزالة الإعدادات التي كتبها هذا السكربت (لا يزيل تثبيت Node / CLI)؛ `--yes` يتخطى prompt |
| `--help` | عرض كل الخيارات |

Windows مع المعلمات (بما يطابق الجدول أعلاه: `-Key`، `-Domain`، `-Model`، `-Lang`، `-Target`، `-Yes`، `-NoInstall`، `-NoVerify`، `-DryRun`، `-Uninstall`):

```powershell
& ([scriptblock]::Create((irm https://qcode.cc/install/claude-code.ps1))) -Key cr_xxx -Yes
```

(النمط نفسه لـ `codex.ps1`.)

## المعاينة أولًا: --dry-run

مع `--dry-run` (Windows: `-DryRun`) لا يطبع السكربت سوى خطته: الملف الذي ستُكتب فيه الإعدادات، والكتلة المُدارة كاملة (المفتاح مُقنّعًا بصيغة `cr_****` مع آخر أربعة أحرف منه)، والمفاتيح التي سيزامنها في `~/.claude/settings.json`، وفي `config.toml` و`auth.json` الخاصين بـ Codex، والبرامج التي سيثبتها، وطلب التحقق الذي سيرسله. لا يكتب أي ملفات، ولا يثبت أي شيء، ولا يرسل أي طلب تحقق؛ بل يشغّل فقط فحص زمن الاستجابة (يُتخطى عند تمرير `--domain`). وعند غياب المفتاح يستخدم قيمة بديلة ولا يتوقف ليسأل.

## إلغاء التثبيت: --uninstall

`--uninstall` (Windows: `-Uninstall`) يزيل الإعدادات التي كتبها هذا السكربت والتي لا تزال قيمها مطابقة لما كتبه. لا يزيل تثبيت Node أو CLI؛ وفي النهاية يطبع أمر `npm uninstall -g …` المطابق لتشغيله إذا أردت. يسرد الملفات التي سيغيّرها ويسأل أولًا؛ أضف `--yes` (Windows: `-Yes`) لتخطي prompt. وعند دمجه مع `--dry-run` فإنه يسردها فقط ولا يغيّر شيئًا.

```bash
curl -fsSL https://qcode.cc/install/claude-code.sh | bash -s -- --dry-run
curl -fsSL https://qcode.cc/install/claude-code.sh | bash -s -- --uninstall
curl -fsSL https://qcode.cc/install/codex.sh | bash -s -- --uninstall --yes
```

```powershell
& ([scriptblock]::Create((irm https://qcode.cc/install/claude-code.ps1))) -DryRun
& ([scriptblock]::Create((irm https://qcode.cc/install/claude-code.ps1))) -Uninstall
& ([scriptblock]::Create((irm https://qcode.cc/install/codex.ps1))) -Uninstall -Yes
```

- **Claude Code (macOS / Linux)**: الكتلة المُدارة `# >>> qcode.cc claude-code >>>` في ملفات إعداد shell لديك (وفي fish، الكتلة نفسها في `conf.d/qcode.fish`)؛ وفي `env` ضمن `~/.claude/settings.json`، و`ANTHROPIC_BASE_URL` على `qcode.cc` و`ANTHROPIC_AUTH_TOKEN` المرافق له.
- **Claude Code (Windows)**: متغيرات البيئة على مستوى المستخدم التي عيّنها السكربت، فقط حيث لا تزال القيمة مطابقة؛ وتُنسخ القيم القديمة احتياطيًا إلى `%USERPROFILE%\.qcode\` أولًا. يُحتفظ بـ `ANTHROPIC_MODEL`؛ أزله بنفسك إذا أردت.
- **Codex**: جدول `[model_providers.qcode]` والمفاتيح من المستوى الأعلى التي كتبها هذا السكربت في `config.toml` (تُحتفظ بالمفاتيح التي لم تعد قيمها مطابقة ويُبلّغ عنها)، و`OPENAI_API_KEY` الذي كتبه هذا السكربت في `auth.json`.

يُحتفظ بعنوان مزوّد آخر ومفتاحه، وبقية إعداداتك، وإعداد PATH الخاص بـ CLI جميعًا؛ ويُنسخ كل ملف يغيّره احتياطيًا باسم `.bak.<timestamp>` أولًا. وعندما لا يوجد ما يُزال، يطبع «No settings written by this script were found.» ويخرج بشكل طبيعي. لا تزول متغيرات البيئة في الطرفيات المفتوحة بالفعل إلا في طرفية جديدة.
## الملفات التي تُكتب وكيفية التراجع

| الأداة / النظام الأساسي | موضع الكتابة | التراجع |
|------|------|------|
| Claude Code (macOS/Linux) | الكتلة المُدارة `# >>> qcode.cc claude-code >>>` في `~/.zshrc` أو `~/.bashrc` | احذف الكتلة المُدارة بالكامل، أو استعد من نسخة `.bak.<timestamp>` الاحتياطية في الدليل نفسه |
| Claude Code (Windows) | 4 متغيرات بيئة على مستوى المستخدم (`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` / `CLAUDE_CODE_AUTO_MODE_SERVER`؛ بالإضافة إلى `ANTHROPIC_MODEL` مع `-Model`) | استعد القيم السابقة من `%USERPROFILE%\.qcode\backup-*.json` |
| Codex (جميع الأنظمة الأساسية) | `~/.codex/config.toml` + `~/.codex/auth.json` | استعد من نسخة `.bak.<timestamp>` الاحتياطية في الدليل نفسه |
| Claude Code (فقط إذا كانت كتلة `env` في `~/.claude/settings.json` تشير إلى مزوّد آخر) | `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` في كتلة `env` تلك (يتحول `ANTHROPIC_API_KEY` إلى `ANTHROPIC_AUTH_TOKEN`)، ولا تُغيَّر إلا بعد تأكيدك؛ ويُحتفظ بكل ما عداها | استعد من نسخة `.bak.<timestamp>` الاحتياطية في الدليل نفسه |

إعادة تشغيل السكربت آمنة دائمًا: تُحدَّث الكتلة المُدارة في مكانها، وتُنسخ ملفات الإعدادات احتياطيًا قبل تحديثها. ولإزالة إعدادات هذا السكربت دفعة واحدة، استخدم `--uninstall` أعلاه.

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

- **يعيد التحقق الخطأ 401** — المفتاح غير صالح أو منتهي الصلاحية: تحقق منه في [لوحة التحكم](https://qcode.cc/dashboard) (تأكد من نسخ البادئة `cr_` كاملة)، ثم أعد تشغيل السكربت
- **يعيد التحقق الخطأ 404** — عنوان URL لنقطة النهاية غير صحيح: يجب أن يكون BASE_URL هو `https://{domain}/api` لـ Claude Code و`https://{domain}/openai` لـ Codex، دون شرطة مائلة في النهاية
- **مهلة الشبكة** — أعد تشغيل السكربت باستخدام نقطة نهاية أخرى (مثل `--domain asia`)؛ الحالة المباشرة لكل نقطة نهاية على [probe.qcode.cc](https://probe.qcode.cc/)
- **الأمر `claude` / `codex` غير موجود بعد التثبيت على Windows** — افتح نافذة PowerShell جديدة (لا يُحدَّث PATH إلا في الجلسات الجديدة)
- **لا تريد أن يثبّت السكربت Node** — أضف `--no-install` (على Windows: `-NoInstall`) لكتابة الإعدادات فقط
- **تريد فحص السكربت أولًا** — افتح <https://qcode.cc/install/claude-code.sh> واقرأ المصدر؛ لا يحتاج السكربت إلى sudo أو حقوق مسؤول، ولا يكتب أبدًا في أدلة النظام
- **«The API key contains invalid characters»** — لُصقت علامات اقتباس أو مسافات أو علامات ترقيم ذكية مع المفتاح. يزيل السكربت علامات الاقتباس والمسافات المحيطة تلقائيًا، لكن الأحرف في الوسط تظل مرفوضة؛ انسخه مرة أخرى من [لوحة التحكم](https://qcode.cc/dashboard)
- **«You are running this script with sudo»** — السكربت **لا يحتاج إلى sudo**. تشغيله باستخدام sudo يكتب الإعدادات في الدليل الرئيسي للمستخدم root، حيث لن يقرأها صدفك أبدًا؛ أعد التشغيل دون sudo
- **«Config was written, but verification did not pass»** — ملفات الإعدادات موجودة بالفعل؛ فشل فحص الاتصال الأخير فقط. اتبع رمز الحالة في الرسالة (401 → أعد التحقق من المفتاح، 404 → تحقق من العنوان، مهلة → جرّب نقطة نهاية أخرى)، ثم أعد التشغيل
- **«The env block in settings.json points Claude Code at a different endpoint»** — استخدمت خدمة ترحيل أخرى أو CC Switch سابقًا. كتلة `env` في `~/.claude/settings.json` لها الأولوية على متغيرات البيئة، لذا سيظل Claude Code يذهب إلى هناك (فحص الاتصال الخاص بالسكربت لا يقرأها وسينجح على أي حال). دع السكربت يحوّل تلك المفاتيح إلى QCode: ينسخ الملف احتياطيًا ويغيّر مفاتيح نقطة النهاية فقط. وإذا رفضت، ينتهي الملخص باللون الأصفر ويكون رمز الخروج 1
- **يصبح Codex أبطأ ويستمر في عرض «Reconnecting… / stream disconnected»** — عادةً ما تكون الجلسة قد تراكمت فيها لقطات الشاشة/الصور: يعيد Codex رفع المحادثة كاملة (مع كل صورة) في كل دور، لذا تعني عشرات لقطات الشاشة عشرات الميغابايتات لكل طلب، وهو ما لا يستطيع اتصال أبطأ إكماله في الوقت المناسب. ابدأ جلسة جديدة باستخدام `/new` (لخّص المهمة في بضع جمل)؛ وعندما تكون الجلسة ضخمة بالفعل، تجنّب `/compact` — إذ يجب أن يرفع طلب الضغط السجل الكامل مرة واحدة أيضًا. من الآن فصاعدًا، ألصق لقطات شاشة أقل في كل جلسة أو صغّرها أولًا