# اسکریپت راه‌اندازی تک‌کلیکی

با یک فرمان از صفر به کارکردن برسید: اسکریپت سریع‌ترین نقطه پایانی را از طریق آزمون تأخیر انتخاب می‌کند، کلید 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 (Command Prompt)، یا اگر پیام «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` در صورت وجود PowerShell 7 را انتخاب می‌کند، 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 هرگز دست‌کاری نمی‌شود. هر زمان بعداً CLI را خواستید، اسکریپت را دوباره اجرا کنید و 2 را انتخاب کنید. حالت غیرتعاملی: `--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 / بدون prompt)

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>` | زبان رابط کاربری؛ به‌طور پیش‌فرض از locale سیستم پیروی می‌کند |
| `--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 …` را چاپ می‌کند تا در صورت تمایل خودتان اجرا کنید. فایل‌هایی را که تغییر خواهد داد فهرست می‌کند و ابتدا می‌پرسد؛ برای صرف‌نظر از prompt، `--yes` (در Windows: `-Yes`) را اضافه کنید. در ترکیب با `--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 برمی‌گرداند** — نشانی نقطه پایانی نادرست است: BASE_URL برای Claude Code باید `https://{domain}/api` و برای Codex باید `https://{domain}/openai` باشد، بدون اسلش انتهایی
- **اتمام مهلت شبکه** — اسکریپت را با نقطه پایانی دیگری (مثلاً `--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` پرهیز کنید — درخواست فشرده‌سازی هم باید یک‌بار کل تاریخچه را بارگذاری کند. از این پس در هر نشست اسکرین‌شات کمتری بچسبانید یا ابتدا آن‌ها را کوچک کنید