نصب OpenClaw و پیکربندی OmniProxy

OpenClaw یک دستیار هوش مصنوعی است که روی رایانه شخصی شما نصب می‌شود. می‌توانید بدون باز نگه داشتن پنجره چت اضافی، مستقیماً از طریق تلگرام، دیسکورد، واتس‌اپ یا فیشو با آن صحبت کنید. گفتگوها و سوابق روی همین رایانه باقی می‌مانند و برنامه می‌تواند مراحل بعدی را به‌صورت محلی ادامه دهد.

قبل از شروع

OpenClaw به Node 24.16 یا بالاتر نیاز دارد. همچنین می‌توانید از Node 26.1 یا بالاتر استفاده کنید که نسخه 26 توصیه می‌شود. Node محیط اجرایی مورد نیاز OpenClaw را فراهم می‌کند.

این برنامه روی macOS، لینوکس و ویندوز قابل نصب است. اگر رایانه نسخه مناسبی از Node را نداشته باشد، اسکریپت نصب به‌طور خودکار یکی را آماده می‌کند: Node 26 در macOS و Node 24 LTS در لینوکس. pnpm تنها در صورتی مورد نیاز است که بخواهید OpenClaw را از سورس کد بسازید.

اگر نسخه قدیمی‌تری از Node نصب شده است، نیازی به حذف آن نیست. در آزمایش مورخ 2026-10-09، نسخه Node سیستم روی این رایانه 24.2.0 بود که پایین‌تر از 24.16 مورد نیاز بود و اسکریپت نصب غیرتعاملی به‌طور خودکار Node 24.21.0 را آماده کرد.

آیا پنجره می‌خواهید

همراه دسکتاپ

• استفاده از نصب‌کننده Hub در ویندوز
• استفاده از DMG گیت‌هاب در macOS
• درگاه محلی (Gateway) می‌تواند در حین راه‌اندازی اولیه نصب شود

توصیه رسمی

اسکریپت نصب

• macOS لینوکس WSL2
• استفاده از PowerShell در ویندوز
• می‌توانید --no-onboard را اضافه کنید

Node از قبل نصب شده است

مدیریت بسته

• npm، pnpm یا bun
• سپس onboard را اجرا کنید
• برای نسخه Node به صفحه نصب مراجعه کنید

نصب و اجرای اولیه

می‌توانید همراه دسکتاپ را با پنجره گرافیکی نصب کنید یا مستقیماً از طریق ترمینال اقدام نمایید. Gateway سرویس محلی مسئول دریافت پیام‌ها، فراخوانی مدل‌ها و بازگرداندن نتایج است. می‌توانید هنگام باز کردن همراه دسکتاپ برای اولین بار، آن را تنظیم کنید.

اگر پنجره می‌خواهید

• ویندوز: دانلود و اجرا کنید OpenClawCompanion-Setup-x64.exe یا OpenClawCompanion-Setup-arm64.exe. نصب‌کننده امضا شده است و شامل تنظیمات، وضعیت سینی سیستم، چت و حالت‌های گره (node) است.
• macOS: دانلود کنید OpenClaw .dmg از بخش Releases گیت‌هاب OpenClaw. فایل dmg ترجیح داده می‌شود، اگرچه می‌توانید از .zipنیز استفاده کنید. پس از نصب، OpenClaw.app را باز کنید. اگر این نسخه شامل فایل macOS نیست، صفحه برنامه macOS را دنبال کنید.

هنگام باز کردن برای اولین بار، می‌توانید اجازه دهید OpenClaw درگاه (Gateway) را روی این رایانه آماده کند یا به یک درگاه از راه دور موجود متصل شوید.

نصب از طریق ترمینال

برای macOS، لینوکس و WSL2 از این دستور استفاده کنید:

curl -fsSL https://openclaw.ai/install.sh | bash

برای PowerShell ویندوز از این دستور استفاده کنید:

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

این اسکریپت سیستم فعلی را شناسایی کرده، در صورت نیاز Node را نصب می‌کند، OpenClaw را نصب کرده و سپس فرآیند راه‌اندازی اولیه (onboarding) را آغاز می‌کند. جریان راه‌اندازی شما را در تنظیمات اولیه راهنمایی می‌کند.

اگر نمی‌خواهید راه‌اندازی را شروع کنید، در macOS، لینوکس و WSL2 از دستور زیر استفاده کنید:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

در ویندوز از گزینه رسمی -NoOnboard استفاده کنید:

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

اگر خودتان Node را مدیریت می‌کنید، می‌توانید از npm، pnpm یا bun نیز استفاده کنید. با npm 12 یا npm 11.16 و بالاتر، اجرا کنید:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

برای npm 11.15 و قدیمی‌تر، حذف کنید --allow-scripts=openclaw. هنگام استفاده از pnpm، اضافه کنید --allow-build=openclaw. برای تفاوت‌های دقیق به صفحه نصب مراجعه کنید.

پس از نصب، این سه دستور را به ترتیب اجرا کنید:

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version نسخه را نمایش می‌دهد، openclaw doctor مشکلات رایج محیطی را بررسی می‌کند و openclaw gateway status نشان می‌دهد که آیا Gateway در حال اجرا است یا خیر. نصب پایه تنها زمانی کامل است که هر سه دستور خروجی عادی داشته باشند.

اگر ترمینال گزارش داد که نمی‌تواند openclawرا پیدا کند، معمولاً دایرکتوری bin جهانی npm در PATH وجود ندارد. PATH لیستی از مکان‌هایی است که ترمینال برای یافتن برنامه‌ها جستجو می‌کند. خروجی node -v, npm prefix -gو echo "$PATH"را مقایسه کنید، دایرکتوری bin مربوطه را به PATH اضافه کرده و سپس ترمینال را دوباره باز کنید.

اگر ~/.openclaw از قبل حاوی پیکربندی در حال استفاده است، اسکریپت نصب پیش‌فرض از همان دایرکتوری استفاده می‌کند. برای نصب یک کپی جداگانه بدون تغییر پیکربندی موجود، اسکریپت غیرتعاملی را اجرا کرده و دایرکتوری جدیدی مشخص کنید:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard رفتار پیش‌فرض این اسکریپت است. در تاریخ 2026-10-09، این دستور OpenClaw 2026.9.9 را نصب کرد. پس از نصب، فایل اجرایی openclaw را از پوشه bin در آن دایرکتوری اجرا کنید.

دریافت مقادیر اتصال از OmniProxy

ابتدا تأیید کنید که OmniProxy در حال اجرا است، سپس لیست مدل‌های آن را باز کرده و سه مقدار زیر را آماده کنید:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copy the full value from the current OmniProxy model list

baseUrl آدرسی است که OpenClaw درخواست‌های مدل را به آن می‌فرستد و باید با /v1ختم شود. هنگام اتصال به OmniProxy، از openai-completions برای apiاستفاده کنید. فقط در صورتی آن را به openai-responses تغییر دهید که مدل واقعاً از طریق /v1/responsesکار کند.

شناسه مدل (Model ID) شناسه کامل مدل در لیست است. آن را دقیقاً همان‌طور که نشان داده شده، شامل هرگونه اسلش، کپی کنید. دو نام زیر فقط ارجاعاتی از مستندات ارائه‌دهنده تا تاریخ 2026-10-09 هستند؛ اگر در لیست ظاهر نمی‌شوند از آن‌ها استفاده نکنید: claude-sonnet-5-5, gpt-6-luna.

حتی اگر درگاه کلید را اعتبارسنجی نکند، apiKey همچنان باید حاوی یک مقدار باشد. می‌توانید از یک رشته جای‌نگهدار (placeholder) استفاده کنید که فقط روی این رایانه استفاده می‌شود. کلید واقعی را در مخزن (repository) قرار ندهید.

وارد کردن پیکربندی ابزار

یک ارائه‌دهنده (Provider) را می‌توان مجموعه‌ای از تنظیمات اتصال دانست که OpenClaw برای یافتن سرویس مدل از آن استفاده می‌کند. در اینجا، نام ارائه‌دهنده omniproxyاست.

دستور زیر را در ترمینال اجرا کنید و آدرس، کلید و دو شناسه مدل را با مقادیر خود جایگزین کنید:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

این دستور ارائه‌دهنده و لیست مدل‌ها را در پیکربندی می‌نویسد. پس از موفقیت‌آمیز بودن دستور، نیازی به راه‌اندازی مجدد Gateway نیست.

سپس، مدل پیش‌فرض را مشخص کنید. ارجاع مدل شامل omniproxy/ به دنبال آن شناسه مدل است. تمام اسلش‌های موجود در شناسه را حفظ کنید. اگر شناسه در لیست مدل‌ها طولانی‌تر از نام کوتاه زیر است، از مقدار کامل لیست استفاده کنید:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning, input, cost, contextWindowو maxTokens همه قابل حذف هستند. وقتی ارائه نمی‌شوند، مدل‌های متنی با استفاده از پیش‌فرض‌ها مدیریت می‌شوند.

همچنین می‌توانید همان تنظیمات را مستقیماً در فایل پیکربندی بنویسید. در پیکربندی اصلی، ارائه‌دهنده تحت models.providersقرار دارد. هر عامل (agent) نیز می‌تواند models.jsonمخصوص خود را داشته باشد؛ عامل یک نمونه دستیار است که در واقع وظایف را دریافت کرده و مدل‌ها را فراخوانی می‌کند. فایل در agent/models.json در دایرکتوری عامل مربوطه تحت ~/.openclaw/agents/قرار دارد.

اگر این models.json حاوی یک baseUrlغیرخالی باشد، آدرس موجود در پیکربندی اصلی را نادیده می‌گیرد (override می‌کند).

بررسی نصب

سه دستور

• openclaw --version
• openclaw doctor
• gateway status

پیکربندی

models.providers

• baseUrl با /v1 ختم می‌شود
• تنظیم api روی completions
• حداقل شناسه مدل را مشخص کنید

انتخاب

provider/model

• از این ارجاع برای اصلی استفاده کنید
• برای کلید، متغیر محیطی را ترجیح دهید
• از لیست درگاه به عنوان منبع حقیقت استفاده کنید

تأیید با یک وظیفه واقعی

وارد یک دایرکتوری پروژه معمولی شوید و یک پیام بسیار کوتاه ارسال کنید. ارجاع مدل در دستور را با شناسه مدل کامل خود جایگزین کنید:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Reply with one word."

--local این وظیفه عامل را به‌صورت محلی اجرا می‌کند، --model مدل مورد استفاده برای این اجرا را مشخص می‌کند و --timeout 300 حداکثر زمان انتظار را روی 300 ثانیه تنظیم می‌کند.

پاسخ واقعی مدل باید در ترمینال ظاهر شود. در تاریخ 2026-10-09، OpenClaw 2026.9.9 با استفاده از این دستور پاسخی دریافت کرد. اولین فراخوانی ممکن است یک یا دو دقیقه طول بکشد.

اگر خطای اصلی Request timed out before a response was generated ظاهر شد، --timeout را افزایش دهید و دوباره درخواست را ارسال کنید. این معمولاً به این معنی است که زمان انتظار کافی نبوده و لزوماً به این معنی نیست که آدرس نادرست است.

پس از موفقیت‌آمیز بودن پاسخ کوتاه، از آن بخواهید یک فایل محلی که مشخص می‌کنید را بخواند. سپس سوابق درخواست OmniProxy را باز کرده و منبع و شناسه مدل نشان داده شده در رکورد را تأیید کنید. خروجی فقط از دستور نسخه یا doctor به این معنی نیست که اتصال مدل به‌طور کامل پیکربندی شده است.

نصب

دستور پاسخ می‌دهد

• شماره نسخه نمایش داده می‌شود
• doctor هیچ مانعی گزارش نمی‌کند
• وضعیت Gateway قابل خواندن است

وظیفه

یک وظیفه کوچک را تکمیل کرد

• مثلاً، خواندن یک فایل محلی
• پاسخ خطا نیست
• ارجاع مدل صحیح است

لاگ‌ها

در درگاه قابل مشاهده است

• منبع OpenClaw است
• شناسه مدل مطابقت دارد
• کلید به مخزن اضافه نشده است

خطاهای رایج

• نمی‌توان openclawرا پیدا کرد: دایرکتوری bin جهانی npm را به PATH اضافه کنید، سپس ترمینال را دوباره باز کنید. اگر در دایرکتوری مشخصی نصب کرده‌اید، فایل اجرایی را از پوشه bin آن دایرکتوری اجرا کنید.
• node -v پایین‌تر از 24.16 است: نیازی به حذف نسخه قدیمی نیست. نسخه Node آماده شده توسط اسکریپت نصب را بررسی کنید، یا از 24.16+ یا 26.1+ همان‌طور که در صفحه نصب توضیح داده شده استفاده کنید. Node 26 توصیه می‌شود.
• مدل ظاهر نمی‌شود: مدل باید در آرایه models تحت models.providers گنجانده شود و حداقل باید همان idرا داشته باشد. تنظیم فقط agents.defaults.models به تنهایی مدل جدیدی را ثبت نمی‌کند.
• پاسخ 400 به نقش توسعه‌دهنده اشاره دارد: وقتی میزبان آدرس api.openai.comنیست، پیش‌فرض را حفظ کنید و supportsDeveloperRole را روی true تنظیم نکنید. حتی اگر روی true تنظیم شود، باز هم نادیده گرفته می‌شود.
• سریعاً زمان آن تمام می‌شود (timeout): --timeout را قبل از تغییر آدرس به بیش از 300 ثانیه افزایش دهید.
• فراخوانی ابزار پس از انتخاب gpt-6-lunaشکست می‌خورد: این از Chat Completions پشتیبانی می‌کند؛ فراخوانی تابع در Chat Completions تنها زمانی پشتیبانی می‌شود که reasoning_effort برابر با noneباشد. اگر شناسه موجود در لیست با این متفاوت است، از شناسه‌ای که در لیست نشان داده شده استفاده کنید.
• آدرس قابل دسترسی نیست: تأیید کنید که OmniProxy در حال اجرا است، baseUrl با /v1ختم می‌شود و آدرس نوشته شده در پیکربندی قابل دسترسی است. سایر آدرس‌های شبکه خصوصی باید به‌طور جداگانه مجاز شوند.
• درخواست‌ها پس از پیکربندی همچنان به آدرس دیگری می‌روند: بررسی کنید که آیا models.json آن عامل حاوی baseUrl متفاوتی است.

متفاوتی است.

مراجع رسمی

برای مراحل نصب، به نصب OpenClaw مراجعه کنید. برای پیکربندی ارائه‌دهنده سفارشی، به ارائه‌دهندگان سفارشی و فیلدهای پیکربندی مراجعه کنید. برای شناسه‌های مدل استفاده شده در مثال‌ها، با نمای کلی مدل Claude و GPT-6 Luna مقایسه کنید.

هر جایگاه را با مقادیر از پیکربندی OmniProxy خود جایگزین کنید. هرگز یک کلید واقعی را منتشر نکنید.

یک نتیجه ذخیره شده یا HTTP 200 به تنهایی سازگاری کامل عامل را اثبات نمی‌کند. منبع و مدل را در گزارش درخواست OmniProxy بررسی کنید.

منابع رسمی · OpenClaw ↗