OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Install overview

جزئیات داخلی نصب‌کننده

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

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

هر سه از Node 22.22.3+، 24.15+ یا 25.9+ پشتیبانی می‌کنند؛ Node 24 هدف پیش‌فرض برای نصب‌های جدید است.

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

install.sh

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

install-cli.sh

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

install.ps1

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

install.sh

روند (install.sh)

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

    از macOS و Linux (از جمله WSL) پشتیبانی می‌کند.

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

    نسخه Node را بررسی می‌کند و در صورت نیاز Node 24 را نصب می‌کند (Homebrew در macOS و اسکریپت‌های راه‌اندازی NodeSource در Linux برای apt/dnf/yum). در macOS، ‏Homebrew فقط زمانی نصب می‌شود که نصب‌کننده برای Node یا Git به آن نیاز داشته باشد. Node 22.22.3+، Node 24.15+ و Node 25.9+ پشتیبانی می‌شوند؛ Node 23 پشتیبانی نمی‌شود. در Alpine/musl Linux، نصب‌کننده به‌جای NodeSource از بسته‌های apk استفاده می‌کند و نسخه واقعی SQLite پیوندشده را بررسی می‌کند. جریان‌های فعلی بسته‌های نسخه پایدار Alpine ممکن است Node به‌اندازه کافی جدیدی را همراه با SQLite سیستمی آسیب‌پذیر ارائه کنند؛ در این صورت، به‌جای آن از یک کانتینر رسمی node:24-alpine یا میزبانی مبتنی بر glibc استفاده کنید.

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

    اگر Git موجود نباشد، آن را با استفاده از مدیر بسته شناسایی‌شده، از جمله Homebrew در macOS و apk در Alpine، نصب می‌کند.

  • نصب OpenClaw

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

  • وظایف پس از نصب

    • فایل اجرایی openclaw که به‌تازگی نصب شده است را برای فرمان‌های بعدی پیدا می‌کند
    • برای نصبی که پیکربندی نشده است، پیش از بررسی‌های doctor یا Gateway فرایند راه‌اندازی اولیه را آغاز می‌کند. با --no-onboard یا در نبود TTY، فرمان تکمیل راه‌اندازی در زمانی دیگر را نمایش می‌دهد.
    • برای نصبی که پیکربندی شده است، سرویس Gateway بارگذاری‌شده را در حد امکان نوسازی و راه‌اندازی مجدد می‌کند و doctor را اجرا می‌کند. ارتقاها در صورت امکان Pluginها را به‌روزرسانی می‌کنند، یا در اجرای بدون رابط کاربری با اعلان‌های فعال، فرمان دستی را نمایش می‌دهند.
    • هنگام اجرای --verify، نسخه نصب‌شده را بررسی می‌کند و تنها پس از وجود پیکربندی، سلامت Gateway را بررسی می‌کند.

    • تشخیص نسخه کاری کد منبع

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

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

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

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

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

    پیش‌فرض

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

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

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

    نصب با Git

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

    نسخه کاری شاخه main در GitHub

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

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

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

    بررسی پس از نصب

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

    install-cli.sh

    روند (install-cli.sh)

  • نصب محیط اجرای محلی Node

    یک فایل tar از نسخه سنجاق‌شده و پشتیبانی‌شده Node LTS را (نسخه در اسکریپت تعبیه شده و مستقل به‌روزرسانی می‌شود، پیش‌فرض 24.15.0) در <prefix>/tools/node-v<version> بارگیری می‌کند و SHA-256 را بررسی می‌کند. Linux ARMv7 از Node 22.22.3 استفاده می‌کند، زیرا فایل‌های اجرایی رسمی Node 24+ برای ARMv7 موجود نیستند. در Alpine/musl Linux، که Node فایل‌های tar سازگار با محیط اجرای سنجاق‌شده منتشر نمی‌کند، nodejs و npm را با apk نصب می‌کند و سپس هم Node و هم کتابخانه واقعی SQLite پیوندشده را بررسی می‌کند. جریان‌های فعلی بسته‌های نسخه پایدار Alpine ممکن است حتی با Node به‌اندازه کافی جدید همچنان به SQLite آسیب‌پذیر پیوند بخورند؛ اگر بررسی ایمنی بسته را رد کرد، از یک کانتینر رسمی node:24-alpine یا میزبانی مبتنی بر glibc استفاده کنید.

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

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

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

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

  • نوسازی سرویس Gateway بارگذاری‌شده

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

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

    پیش‌فرض

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

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

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

    نصب با Git

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

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

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

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

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
    مرجع پرچم‌ها
    پرچم توضیحات
    --prefix <path> پیشوند نصب (پیش‌فرض: ~/.openclaw)
    --install-method | --method npm|git انتخاب روش نصب (پیش‌فرض: npm)
    --npm میان‌بر روش npm
    --git | --github میان‌بر روش git
    --git-dir | --dir <path> دایرکتوری checkout در Git (پیش‌فرض: ~/openclaw)
    --version <ver> نسخه یا dist-tag مربوط به OpenClaw (پیش‌فرض: latest)
    --node-version <ver> نسخه Node (پیش‌فرض: 24.15.0؛ 22.22.3 در Linux ARMv7)
    --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> نسخه یا dist-tag مربوط به OpenClaw
    OPENCLAW_NODE_VERSION=<ver> نسخه Node
    OPENCLAW_HOME=<path> دایرکتوری پایه برای وضعیت OpenClaw و مسیرهای پیش‌فرض git/راه‌اندازی اولیه
    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 (پیش‌فرض: error)

    install.ps1

    روند (install.ps1)

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

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

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

    اگر موجود نباشد، ابتدا نصب از طریق winget، سپس Chocolatey و بعد Scoop امتحان می‌شود. اگر هیچ مدیر بسته‌ای در دسترس نباشد، اسکریپت فایل zip رسمی Node.js 24 برای Windows را در %LOCALAPPDATA%\OpenClaw\deps\portable-node دانلود می‌کند و آن را به PATH فرایند فعلی و کاربر می‌افزاید. Node 22.22.3+، Node 24.15+ و Node 25.9+ پشتیبانی می‌شوند؛ Node 23 پشتیبانی نمی‌شود.

  • نصب OpenClaw

    • روش npm (پیش‌فرض): نصب سراسری npm با استفاده از -Tag انتخاب‌شده که از یک دایرکتوری موقت و قابل‌نوشتن نصب‌کننده اجرا می‌شود تا پوسته‌هایی که در پوشه‌های محافظت‌شده‌ای مانند C:\ باز شده‌اند نیز همچنان کار کنند
    • روش git: شبیه‌سازی/به‌روزرسانی مخزن، نصب/ساخت با pnpm و نصب wrapper در %USERPROFILE%\.local\bin\openclaw.cmd. اگر Git موجود نباشد، اسکریپت MinGit محلیِ کاربر را در %LOCALAPPDATA%\OpenClaw\deps\portable-git راه‌اندازی می‌کند و آن را به PATH فرایند فعلی و کاربر می‌افزاید.

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

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

  • مدیریت خطاها

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

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

    پیش‌فرض

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

    نصب Git

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

    checkout شاخه main در GitHub

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

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

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

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

    powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
    مرجع پرچم‌ها
    پرچم توضیحات
    -InstallMethod npm|git روش نصب (پیش‌فرض: npm)
    -Tag <tag|version|spec> dist-tag، نسخه یا مشخصات بسته 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 و خودکارسازی

    برای اجرای قابل‌پیش‌بینی، از پرچم‌ها/متغیرهای محیطی غیرتعاملی استفاده کنید.

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

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

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

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

    install-cli.sh (JSON)

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

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

    powershell
    & ([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 پوسته اضافه کند (اگر آن فایل‌ها وجود داشته باشند).

    Windows: "npm error spawn git / ENOENT"

    نصب‌کننده را دوباره اجرا کنید تا بتواند MinGit محلیِ کاربر را راه‌اندازی کند، یا Git for Windows را نصب کرده و PowerShell را دوباره باز کنید.

    Windows: "openclaw is not recognized"

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

    Windows: نحوه دریافت خروجی مشروح نصب‌کننده

    install.ps1 گزینه -Verbose را ارائه نمی‌کند. برای عیب‌یابی در سطح اسکریپت، از ردیابی PowerShell استفاده کنید:

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

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

    مرتبط

    Was this useful?
    On this page

    On this page