English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Install overview

سازوکارهای داخلی نصب‌کننده

OpenClaw سه اسکریپت نصب ارائه می‌کند که از openclaw.ai سرو می‌شوند.

اسکریپت پلتفرم کاری که انجام می‌دهد
install.sh macOS / Linux / WSL در صورت نیاز Node را نصب می‌کند، OpenClaw را از طریق npm (پیش‌فرض) یا git نصب می‌کند، و می‌تواند راه‌اندازی اولیه را اجرا کند.
install-cli.sh macOS / Linux / WSL Node + OpenClaw را در یک پیشوند محلی (~/.openclaw) با حالت‌های npm یا git checkout نصب می‌کند. نیازی به دسترسی ریشه نیست.
install.ps1 Windows (PowerShell) در صورت نیاز Node را نصب می‌کند، OpenClaw را از طریق npm (پیش‌فرض) یا git نصب می‌کند، و می‌تواند راه‌اندازی اولیه را اجرا کند.

فرمان‌های سریع

install.sh

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

install-cli.sh

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help

install.ps1

iwr -useb https://openclaw.ai/install.ps1 | iex

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun

install.sh

جریان (install.sh)

  • تشخیص سیستم‌عامل

    از macOS و Linux (از جمله WSL) پشتیبانی می‌کند. اگر macOS تشخیص داده شود، در صورت نبود Homebrew آن را نصب می‌کند.

  • اطمینان از Node.js 24 به‌صورت پیش‌فرض

    نسخه Node را بررسی می‌کند و در صورت نیاز Node 24 را نصب می‌کند (Homebrew روی macOS، اسکریپت‌های راه‌اندازی NodeSource روی Linux apt/dnf/yum). OpenClaw همچنان برای سازگاری از Node 22 LTS، در حال حاضر 22.14+، پشتیبانی می‌کند.

  • اطمینان از وجود Git

    در صورت نبود Git آن را نصب می‌کند.

  • نصب OpenClaw

    • روش npm (پیش‌فرض): نصب سراسری npm
    • روش git: شبیه‌سازی/به‌روزرسانی مخزن، نصب وابستگی‌ها با pnpm، ساخت، سپس نصب wrapper در ~/.local/bin/openclaw

  • کارهای پس از نصب

    • یک سرویس gateway بارگذاری‌شده را به بهترین شکل ممکن تازه‌سازی می‌کند (openclaw gateway install --force، سپس راه‌اندازی مجدد)
    • در ارتقاها و نصب‌های git، openclaw doctor --non-interactive را اجرا می‌کند (بهترین تلاش)
    • در صورت مناسب بودن، راه‌اندازی اولیه را تلاش می‌کند (TTY در دسترس باشد، راه‌اندازی اولیه غیرفعال نشده باشد، و بررسی‌های bootstrap/config موفق باشند)
    • مقدار پیش‌فرض SHARP_IGNORE_GLOBAL_LIBVIPS=1 را تنظیم می‌کند

    • تشخیص checkout منبع

    اگر داخل یک checkout از OpenClaw اجرا شود (package.json + pnpm-workspace.yaml)، اسکریپت این گزینه‌ها را پیشنهاد می‌کند:

    • استفاده از checkout (git)، یا
    • استفاده از نصب سراسری (npm)

    اگر TTY در دسترس نباشد و هیچ روش نصبی تنظیم نشده باشد، به‌صورت پیش‌فرض از npm استفاده می‌کند و هشدار می‌دهد.

    اسکریپت برای انتخاب روش نامعتبر یا مقدارهای نامعتبر --install-method با کد 2 خارج می‌شود.

    نمونه‌ها (install.sh)

    پیش‌فرض

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

    رد کردن راه‌اندازی اولیه

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

    نصب Git

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

    GitHub main از طریق npm

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --version main

    اجرای آزمایشی

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
    مرجع پرچم‌ها
    پرچم توضیح
    --install-method npm|git انتخاب روش نصب (پیش‌فرض: npm). نام مستعار: --method
    --npm میان‌بر برای روش npm
    --git میان‌بر برای روش git. نام مستعار: --github
    --version <version|dist-tag|spec> نسخه npm، dist-tag، یا مشخصات بسته (پیش‌فرض: latest)
    --beta در صورت وجود از beta dist-tag استفاده می‌کند، وگرنه به latest برمی‌گردد
    --git-dir <path> دایرکتوری checkout (پیش‌فرض: ~/openclaw). نام مستعار: --dir
    --no-git-update برای checkout موجود، git pull را رد می‌کند
    --no-prompt اعلان‌ها را غیرفعال می‌کند
    --no-onboard راه‌اندازی اولیه را رد می‌کند
    --onboard راه‌اندازی اولیه را فعال می‌کند
    --dry-run کنش‌ها را بدون اعمال تغییرات چاپ می‌کند
    --verbose خروجی اشکال‌زدایی را فعال می‌کند (set -x، لاگ‌های سطح notice در npm)
    --help راهنمای استفاده را نشان می‌دهد (-h)
    مرجع متغیرهای محیطی
    متغیر توضیح
    OPENCLAW_INSTALL_METHOD=git|npm روش نصب
    OPENCLAW_VERSION=latest|next|main|<semver>|<spec> نسخه npm، dist-tag، یا مشخصات بسته
    OPENCLAW_BETA=0|1 استفاده از beta در صورت وجود
    OPENCLAW_GIT_DIR=<path> دایرکتوری checkout
    OPENCLAW_GIT_UPDATE=0|1 تغییر وضعیت به‌روزرسانی‌های git
    OPENCLAW_NO_PROMPT=1 غیرفعال کردن اعلان‌ها
    OPENCLAW_NO_ONBOARD=1 رد کردن راه‌اندازی اولیه
    OPENCLAW_DRY_RUN=1 حالت اجرای آزمایشی
    OPENCLAW_VERBOSE=1 حالت اشکال‌زدایی
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice سطح لاگ npm
    SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 کنترل رفتار sharp/libvips (پیش‌فرض: 1)

    install-cli.sh

    جریان (install-cli.sh)

  • نصب runtime محلی Node

    یک آرشیو tarball پین‌شده و پشتیبانی‌شده Node LTS را (نسخه در اسکریپت جاسازی شده و مستقل به‌روزرسانی می‌شود) در <prefix>/tools/node-v<version> دانلود می‌کند و SHA-256 را تأیید می‌کند.

  • اطمینان از وجود Git

    اگر Git وجود نداشته باشد، تلاش می‌کند آن را از طریق apt/dnf/yum روی Linux یا Homebrew روی macOS نصب کند.

  • نصب OpenClaw زیر پیشوند

    • روش npm (پیش‌فرض): زیر پیشوند با npm نصب می‌کند، سپس wrapper را در <prefix>/bin/openclaw می‌نویسد
    • روش git: یک checkout را شبیه‌سازی/به‌روزرسانی می‌کند (پیش‌فرض ~/openclaw) و همچنان wrapper را در <prefix>/bin/openclaw می‌نویسد

  • تازه‌سازی سرویس gateway بارگذاری‌شده

    اگر یک سرویس gateway از همان پیشوند از قبل بارگذاری شده باشد، اسکریپت openclaw gateway install --force، سپس openclaw gateway restart را اجرا می‌کند، و سلامت gateway را به بهترین شکل ممکن بررسی می‌کند.

    • نمونه‌ها (install-cli.sh)

    پیش‌فرض

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

    پیشوند سفارشی + نسخه

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest

    نصب Git

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw

    خروجی JSON برای خودکارسازی

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

    اجرای راه‌اندازی اولیه

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
    مرجع پرچم‌ها
    پرچم توضیح
    --prefix <path> پیشوند نصب (پیش‌فرض: ~/.openclaw)
    --install-method npm|git انتخاب روش نصب (پیش‌فرض: npm). نام مستعار: --method
    --npm میان‌بر برای روش npm
    --git, --github میان‌بر برای روش git
    --git-dir <path> دایرکتوری git checkout (پیش‌فرض: ~/openclaw). نام مستعار: --dir
    --version <ver> نسخه OpenClaw یا dist-tag (پیش‌فرض: latest)
    --node-version <ver> نسخه Node (پیش‌فرض: 22.22.0)
    --json رویدادهای NDJSON را منتشر می‌کند
    --onboard پس از نصب openclaw onboard را اجرا می‌کند
    --no-onboard راه‌اندازی اولیه را رد می‌کند (پیش‌فرض)
    --set-npm-prefix روی Linux، اگر پیشوند فعلی قابل نوشتن نیست، پیشوند npm را به ~/.npm-global اجبار می‌کند
    --help راهنمای استفاده را نشان می‌دهد (-h)
    مرجع متغیرهای محیطی
    متغیر توضیح
    OPENCLAW_PREFIX=<path> پیشوند نصب
    OPENCLAW_INSTALL_METHOD=git|npm روش نصب
    OPENCLAW_VERSION=<ver> نسخه OpenClaw یا dist-tag
    OPENCLAW_NODE_VERSION=<ver> نسخه Node
    OPENCLAW_GIT_DIR=<path> دایرکتوری checkout Git برای نصب‌های git
    OPENCLAW_GIT_UPDATE=0|1 روشن/خاموش کردن به‌روزرسانی‌های git برای checkoutهای موجود
    OPENCLAW_NO_ONBOARD=1 رد کردن راه‌اندازی اولیه
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice سطح گزارش npm
    SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 کنترل رفتار sharp/libvips (پیش‌فرض: 1)

    install.ps1

    جریان (install.ps1)

  • اطمینان از محیط PowerShell + Windows

    به PowerShell 5+ نیاز دارد.

  • اطمینان از Node.js 24 به‌صورت پیش‌فرض

    اگر موجود نباشد، نصب از طریق winget، سپس Chocolatey، و سپس Scoop را امتحان می‌کند. Node 22 LTS، در حال حاضر 22.14+، برای سازگاری همچنان پشتیبانی می‌شود.

  • نصب OpenClaw

    • روش npm (پیش‌فرض): نصب سراسری npm با استفاده از -Tag انتخاب‌شده، اجراشده از یک دایرکتوری موقت نصب‌کننده که قابل نوشتن است تا پوسته‌هایی که در پوشه‌های محافظت‌شده مانند C:\ باز شده‌اند همچنان کار کنند
    • روش git: clone/update مخزن، نصب/ساخت با pnpm، و نصب wrapper در %USERPROFILE%\.local\bin\openclaw.cmd

  • کارهای پس از نصب

    • در صورت امکان، دایرکتوری bin لازم را به PATH کاربر اضافه می‌کند
    • یک سرویس Gateway بارگذاری‌شده را به‌صورت best-effort تازه‌سازی می‌کند (openclaw gateway install --force، سپس راه‌اندازی مجدد)
    • هنگام ارتقاها و نصب‌های git، openclaw doctor --non-interactive را اجرا می‌کند (best effort)

  • مدیریت شکست‌ها

    نصب‌های iwr ... | iex و scriptblock یک خطای terminating گزارش می‌کنند بدون اینکه جلسه PowerShell فعلی بسته شود. نصب‌های مستقیم powershell -File / pwsh -File همچنان برای automation با کد غیرصفر خارج می‌شوند.

    • نمونه‌ها (install.ps1)

    پیش‌فرض

    iwr -useb https://openclaw.ai/install.ps1 | iex

    نصب Git

    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git

    شاخه main در GitHub از طریق npm

    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main

    دایرکتوری git سفارشی

    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

    اجرای آزمایشی

    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun

    ردیابی اشکال‌زدایی

    # install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
    مرجع flagها
    Flag توضیح
    -InstallMethod npm|git روش نصب (پیش‌فرض: npm)
    -Tag <tag|version|spec> dist-tag، نسخه، یا package spec برای npm (پیش‌فرض: latest)
    -GitDir <path> دایرکتوری checkout (پیش‌فرض: %USERPROFILE%\openclaw)
    -NoOnboard رد کردن راه‌اندازی اولیه
    -NoGitUpdate رد کردن git pull
    -DryRun فقط چاپ کارها
    مرجع متغیرهای محیطی
    متغیر توضیح
    OPENCLAW_INSTALL_METHOD=git|npm روش نصب
    OPENCLAW_GIT_DIR=<path> دایرکتوری checkout
    OPENCLAW_NO_ONBOARD=1 رد کردن راه‌اندازی اولیه
    OPENCLAW_GIT_UPDATE=0 غیرفعال کردن git pull
    OPENCLAW_DRY_RUN=1 حالت اجرای آزمایشی

    CI و automation

    برای اجراهای قابل پیش‌بینی از flagها/env vars غیرتعاملی استفاده کنید.

    install.sh (npm غیرتعاملی)

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

    install.sh (git غیرتعاملی)

    OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

    install-cli.sh (JSON)

    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

    install.ps1 (رد کردن راه‌اندازی اولیه)

    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

    عیب‌یابی

    چرا Git لازم است؟

    Git برای روش نصب git لازم است. برای نصب‌های npm نیز Git همچنان بررسی/نصب می‌شود تا وقتی وابستگی‌ها از URLهای git استفاده می‌کنند، از شکست‌های spawn git ENOENT جلوگیری شود.

    چرا npm در Linux با EACCES روبه‌رو می‌شود؟

    بعضی تنظیمات Linux پیشوند سراسری npm را به مسیرهای متعلق به root اشاره می‌دهند. install.sh می‌تواند پیشوند را به ~/.npm-global تغییر دهد و exportهای PATH را به فایل‌های rc پوسته اضافه کند (وقتی آن فایل‌ها وجود داشته باشند).

    مشکلات sharp/libvips

    اسکریپت‌ها به‌صورت پیش‌فرض SHARP_IGNORE_GLOBAL_LIBVIPS=1 را تنظیم می‌کنند تا sharp در برابر libvips سیستمی ساخته نشود. برای override کردن:

    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    Windows: "npm error spawn git / ENOENT"

    Git for Windows را نصب کنید، PowerShell را دوباره باز کنید، و نصب‌کننده را دوباره اجرا کنید.

    Windows: "openclaw is not recognized"

    npm config get prefix را اجرا کنید و آن دایرکتوری را به PATH کاربر خود اضافه کنید (در Windows پسوند \bin لازم نیست)، سپس PowerShell را دوباره باز کنید.

    Windows: چگونه خروجی پرجزئیات نصب‌کننده را بگیرید

    install.ps1 در حال حاضر switch به نام -Verbose ارائه نمی‌کند. برای diagnostics در سطح اسکریپت از ردیابی PowerShell استفاده کنید:

    Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
    openclaw پس از نصب پیدا نشد

    معمولاً مشکل PATH است. عیب‌یابی Node.js را ببینید.

    مرتبط