آموزش کامل OpenClaw: راه‌اندازی امن دستیار هوش مصنوعی شخصی

OpenClaw یک دستیار هوش مصنوعی self-hosted است که Gateway را روی دستگاه یا سرور شما اجرا می‌کند و می‌تواند مدل، فایل، مرورگر، اپ، پیام‌رسان، Skill، پلاگین، node و کار زمان‌بندی‌شده را به هم متصل کند. دامنه آن از یک coding copilot وسیع‌تر است: همان ایجنت می‌تواند در داشبورد محلی پاسخ دهد، پیام Telegram دریافت کند، فایل بخواند، دستگاه جفت‌شده را کنترل کند یا automation اجرا کند—اگر شما این اختیارها را بدهید.

این گستردگی همان ریسک اصلی است. مستندات امنیتی رسمی OpenClaw برای هر Gateway یک مرز اعتماد تک‌اپراتوری در نظر می‌گیرند؛ این سیستم دیوار ایزوله‌سازی چندمستاجری در برابر کاربران متخاصم نیست. بنابراین نصب، هویت، شبکه، credential، اختیار ابزار و audit در این آموزش بخش فرعی محسوب نمی‌شوند.

این راهنما در ۱۵ مرداد ۱۴۰۵ (۶ اوت ۲۰۲۶) با مستندات رسمی OpenClaw و مخزن رسمی تطبیق داده شده است. فرمان‌ها و تنظیمات به‌سرعت تغییر می‌کنند؛ نسخه نصب‌شده را با مستندات زنده بسنجید.

تصویر رسمی از مخزن پروژه OpenClaw.

تفاوت OpenClaw با Codex و Claude Code

OpenClaw برای یک دستیار ماندگار میان پیام‌رسان، دستگاه، مرورگر، حافظه و اتوماسیون مناسب است. اگر کار اصلی مهندسی داخل مخزن است، OpenAI Codex، Claude Code یا OpenCode انتخاب تخصصی‌تری هستند.

OpenClaw می‌تواند coding tool فراخوانی کند، Claude Code را attach کند یا از پلاگین Codex App Server استفاده کند. تفاوت معماری است: OpenClaw دستیار و Gateway بلندمدت است؛ coding agent معمولاً worker مخزن‌محور. اعتبارنامه و اختیار این دو را جدا نگه دارید مگر integration واقعاً به هر دو نیاز داشته باشد.

معماری را پیش از نصب بشناسید

یک استقرار پایه شامل این لایه‌هاست:

• Gateway: کنترل‌پلین ماندگار session، channel، ابزار، node، task و Control UI؛
• Agent workspace: فایل‌های هویت، کاربر، دستور، حافظه، ابزار و standing order؛
• Model provider: مدل محلی یا راه‌دور برای inference؛
• ابزار و پلاگین: شل، فایل، مرورگر، پیام‌رسان، حافظه، Skill و MCP؛
• کانال‌ها: Telegram، Discord، Slack، WhatsApp، Signal، iMessage و موارد پشتیبانی‌شده؛
• Nodeها: رایانه یا دستگاه جفت‌شده با قابلیت‌های انتخابی؛
• Sandbox: backend ایزوله اختیاری برای اجرای ابزار؛ خود Gateway روی host می‌ماند.

هر ارتباط میان این لایه‌ها تصمیم اعتماد است. پیام کاربر تأییدشده می‌تواند محتوای وب مخرب داشته باشد؛ مدل معتبر نیز می‌تواند اشتباه تخریبی کند و پلاگین واقعی نیز ممکن است اختیار بیش از حد بخواهد.

نصب و onboarding هدایت‌شده

راهنمای رسمی فعلی به نسخه پشتیبانی‌شده Node.js و credential یک ارائه‌دهنده مدل نیاز دارد. در macOS یا Linux:

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

در Windows PowerShell:

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

اسکریپت راه‌دور را پیش از اجرا بررسی کنید، به‌ویژه روی سیستمی که فایل شخصی یا credential دارد. سپس setup هدایت‌شده را اجرا کنید:

openclaw onboard --install-daemon

Wizard دسترسی‌های AI موجود را پیدا، با یک completion واقعی تأیید و workspace، Gateway و قابلیت‌های اختیاری را پیکربندی می‌کند. برای provider سفارشی، Gateway راه‌دور، channel، daemon، Skill یا import پیشرفته از مسیر کلاسیک استفاده کنید:

openclaw onboard --classic

کنترل‌پلین را تأیید کنید:

openclaw gateway status
openclaw health
openclaw dashboard

پورت محلی پیش‌فرض در quickstart فعلی 18789 است. بازشدن dashboard روی localhost مجوز عمومی‌کردن آن نیست.

با کمترین قابلیت شروع کنید

در مرحله اول channel، plugin، browser control، device node و automation را رد کنید. یک مدل، یک workspace محلی و یک گفت‌وگوی Control UI بسازید. سپس قابلیت‌ها را تک‌تک اضافه و بعد از هر تغییر مرز اعتماد audit امنیتی اجرا کنید.

درخواست اول بهتر است فقط‌خواندنی باشد:

فایل‌های این workspace را خلاصه کن. فرمان اجرا نکن، مرورگر باز نکن،
پیام نفرست، فایل تغییر نده و کار زمان‌بندی‌شده نساز.

رخدادهای ابزار و خروجی واقعی را ببینید. پاسخ دوستانه ثابت نمی‌کند ابزارهای غیرضروری غیرفعال بوده‌اند.

audit امنیتی پیش از اتصال پیام‌رسان

راهنمای رسمی این فرمان‌ها را پیشنهاد می‌کند:

openclaw security audit
openclaw security audit --deep
openclaw security audit --json

حالت --deep probe زنده Gateway و بررسی عمیق‌تر plugin یا Skill را اضافه می‌کند. پیش از --fix یافته‌ها را بخوانید؛ remediation خودکار محدود است و نمی‌تواند مدل اعتماد شما را تعیین کند.

اولویت رسیدگی:

1. DM یا group باز همراه ابزار قدرتمند؛
2. bind عمومی یا نبود احراز هویت Gateway؛
3. browser control، node یا remote debugging باز؛
4. مجوز ضعیف فایل state، config و credential؛
5. plugin یا Skill بدون تصمیم اعتماد صریح؛
6. اختیار شل یا فایل unsandboxed بیش از نیاز.

OpenClaw برای قرار دادن افراد نامطمئن پشت یک ایجنت مشترک طراحی نشده است. خانواده، تیم، مشتری یا tenant جدا به Gateway و credential جدا و ترجیحاً OS user، container یا host جدا نیاز دارند.

انتخاب sandbox و سیاست workspace

OpenClaw می‌تواند Gateway را روی host نگه دارد و ابزار را در Docker یا backend پشتیبانی‌شده اجرا کند. حالت‌های دسترسی فعلی:

• none: sandbox workspace خود را دارد و workspace ایجنت را نمی‌بیند؛
• ro: workspace به‌صورت فقط‌خواندنی mount می‌شود؛
• rw: دسترسی خواندن و نوشتن.

برای ایجنتی که پیام نامطمئن دریافت می‌کند از none یا ro آغاز کنید. اگر ایجنت‌ها نباید state یکدیگر را ببینند scope را per-agent یا per-session قرار دهید. Sandbox شعاع آسیب فایل و process را کم می‌کند، اما credential، session مرورگر یا API بیرونی را خودکار ایمن نمی‌کند.

برای ایجنت عمومی از elevated tool سراسری دوری کنید. اگر یک workflow به host نیاز دارد، آن را ایجنتی جدا با allowlist فرستنده، سیاست ابزار و workspace محدود کنید.

مجوزهای macOS را جداگانه بررسی کنید

اپ macOS بسته به قابلیت فعال ممکن است Automation، Notifications، Accessibility، Screen Recording، Microphone، Speech Recognition، Camera یا Location بخواهد.

اسکرین‌شات رسمی از مستندات onboarding اپ macOS.

تمام دکمه‌های Grant را نزنید. فقط قابلیت لازم برای workflow آزموده‌شده را فعال کنید. Accessibility و Screen Recording دامنه‌ای بسیار فراتر از چت‌بات دارند و Camera، Microphone و Location پیامدهای حریم خصوصی جداگانه دارند. تأیید macOS ثابت نمی‌کند ایجنت داده را به‌درستی مصرف خواهد کرد.

قرارداد workspace

OpenClaw در صورت وجود فایل‌های AGENTS.md، SOUL.md، TOOLS.md، IDENTITY.md، USER.md، HEARTBEAT.md، BOOTSTRAP.md و MEMORY.md آن‌ها را خودکار inject می‌کند. نقش‌ها را جدا نگه دارید:

• AGENTS.md: قواعد عملیاتی، standing order، approval gate و escalation؛
• SOUL.md: لحن و persona، نه مجوز عمل؛
• TOOLS.md: یادداشت و قرارداد امن ابزار؛
• IDENTITY.md: هویت و نقش اعلام‌شده ایجنت؛
• USER.md: ترجیح‌های کم‌حجم و مناسب برای نگه‌داری؛
• HEARTBEAT.md: checklist آگاهی دوره‌ای؛
• MEMORY.md: واقعیت ماندگار و گزینش‌شده، نه transcript؛
• BOOTSTRAP.md: context اولیه setup.

secret، recovery code، کلید خصوصی یا پرونده حساس شخصی را در این فایل‌ها نگذارید. فایلی که هر session بارگذاری می‌شود هم exposure context را بالا می‌برد و هم خسارت session آلوده را.

standing order با اختیار صریح

Standing order برنامه ماندگار است و معمولاً در AGENTS.md قرار می‌گیرد. scope، trigger، approval، escalation، verification و اقدام ممنوع را بنویسید:

## Program: گزارش هفتگی سلامت مخزن

Authority: وضعیت مخزن و CI فقط خوانده و draft محلی نوشته شود.
Trigger: جمعه ساعت 09:00 Asia/Tehran.
Approval gate: post، email، issue، push، merge و deploy ممنوع.
Escalate: نبود دسترسی، CI شکست‌خورده، secret مشکوک یا مخزن مبهم.

Steps:
1. شواهد فقط‌خواندنی از منبع تأییدشده جمع شود.
2. با گزارش قبلی مقایسه شود.
3. `Reports/weekly/YYYY-MM-DD.md` نوشته شود.
4. فایل و لینک منابع تأیید شوند.
5. آماده‌بودن draft به مالک اطلاع داده شود.

Standing order می‌گوید چه کاری مجاز است و cron می‌گوید چه زمانی. سیاست ابزار باید مرز را enforce کند؛ متن به‌تنهایی جلوی فراخوانی خطرناک را نمی‌گیرد.

اتصال channel با pairing و allowlist

هر بار یک channel را با wizard یا راهنمای رسمی خودش تنظیم کنید. حساب bot، مقصد و actionهای پشتیبانی‌شده را دقیقاً تأیید کنید. برای DM از pairing یا allowlist فرستنده و برای group از activation صریح استفاده کنید؛ هر عضو گروه نباید اختیار کامل ابزار ایجنت را به ارث ببرد.

فرستنده ناشناس باید ignore یا pair شود، نه global allow. بعد از setup این موارد را آزمایش کنید:

• کاربر مجاز؛
• کاربر ناشناس؛
• mention گروهی؛
• attachment با دستور مخرب؛
• تلاش ارسال به مقصد تأییدنشده.

ایجنت tool-enabled را در اتاق عمومی رها نکنید و به مقاومت persona در برابر prompt injection تکیه نکنید.

مدل و fallback

فرمان‌های دقیق release خود را از help ببینید:

openclaw models status
openclaw models list
openclaw models configure

انتخاب مدل باید بر اساس reliability ابزار، context، latency، cost و مقاومت دستوری باشد. fallback ممکن است رفتار ایمنی متفاوتی داشته باشد؛ تمام زنجیره fallback را با وظایف عادی و خطرناک یکسان ارزیابی کنید.

راهنمای فعلی ما شناسه و caveat دقیق qwen3.8-max-preview، glm-5.2 و deepseek-v4-flash را پوشش می‌دهد. فقط وقتی wizard زنده یا مستند OpenClaw endpoint را پشتیبانی می‌کند آن را وصل کنید؛ API سازگار، رفتار یکسان tool یا thinking را تضمین نمی‌کند.

کلید provider را در secret store یا reference رسمی نگه دارید، نه openclaw.json، workspace، channel یا screenshot. در صورت پشتیبانی openclaw secrets audit را اجرا و secret حاضر در transcript را rotate کنید.

Skill و plugin به‌عنوان زنجیره تأمین

Skill روش انجام کار را آموزش می‌دهد؛ plugin می‌تواند ابزار اجرایی، hook، provider، channel یا integration اضافه کند. حضور در ClawHub تضمین ایمنی نیست.

پیش از نصب:

1. مالک و مخزن را تأیید کنید؛
2. دستور Skill یا کد plugin را بخوانید؛
3. permission، script، dependency و مقصد شبکه را ببینید؛
4. نسخه و update را بررسی کنید؛
5. از profile آزمایشی و sandbox استفاده کنید؛
6. پس از نصب audit عمیق اجرا کنید.

پس از بررسی --help می‌توان از فرمان‌های فعلی مشابه این‌ها استفاده کرد:

openclaw skills search <term>
openclaw skills info <name>
openclaw plugins list
openclaw plugins doctor

به‌روزرسانی خودکار Skill همان update کد است. workflow حساس را pin و تغییر مادی را دوباره مرور کنید.

مرورگر و device node

Browser control می‌تواند صفحه loginشده را بخواند، فرم submit کند، فایل بگیرد و side effect بسازد. node جفت‌شده نیز بسته به platform و policy می‌تواند screen، camera، location، notification یا system execution بدهد. این‌ها اختیار اپراتوری‌اند.

از browser profile جدا با حداقل حساب، بدون password-manager autofill و download policy روشن استفاده کنید. remote debugging و node control روی شبکه خصوصی authenticated بمانند. دستگاه را آگاهانه pair و token گم‌شده را revoke یا rotate کنید.

بلافاصله پیش از خرید، انتشار، پیام، تغییر حساب، حذف فایل، عملیات مالی یا افشای داده شخصی تأیید بخواهید. درخواست قبلی «کمک با سایت» مجوز تمام کلیک‌ها نیست.

تفاوت task، cron، heartbeat، hook و Task Flow

• Background task: دفتر فعالیت ACP، subagent، cron و CLI جداشده؛
• Cron: زمان دقیق و reminder یک‌باره؛
• Heartbeat: check دوره‌ای context-aware با زمان تقریبی؛
• Hook: script رویدادمحور lifecycle یا message؛
• Task Flow: orchestration ماندگار چندمرحله‌ای؛
• Standing order: دستور و مرز اختیار ماندگار.

Cron برای زمان دقیق، heartbeat برای checklist کوچک دوره‌ای، hook برای رویداد deterministic و Task Flow برای فرایند چندمرحله‌ای قابل بازیابی است. هر مسیر خودکار به credential محدود، timeout، سقف retry، مقصد خروجی، اعلان شکست، audit trail و kill switch نیاز دارد.

اتوماسیون headless همیشه نمی‌تواند سؤال بپرسد. آن را طوری تنظیم کنید که در مجوز جدید fail closed شود، نه اینکه اختیار را خودکار گسترش دهد.

واگذاری به ساب‌ایجنت بدون تکثیر ریسک

ساب‌ایجنت context را جدا یا کار را موازی می‌کند، اما هر child ابزار، مدل، حافظه و sandbox دریافت می‌کند. target agentهای مجاز را محدود و spawn را برای ایجنت بی‌نیاز deny کنید. اگر ایزوله‌ماندن ضروری است برای child الزام sandbox بگذارید و صرفاً inheritance را نپذیرید.

واگذاری برای کار مستقل و خواندنی مناسب است. ایجنت public با ابزار پیام یا شل گسترده spawn نکنید.

backup، update و recovery

پیش از upgrade یا تغییر بزرگ config:

openclaw backup
openclaw status
openclaw doctor

محتوای backup را بشناسید و مانند state زنده محافظت کنید؛ ممکن است identity، session، config یا token داشته باشد. restore را روی نصب جدا بیازمایید. از کانال پشتیبانی‌شده update کنید، release note را بخوانید، Gateway را restart، channel و automation را verify و audit را تکرار کنید.

openclaw reset یا uninstall ابزار عادی رفع اشکال نیست. دقیقاً بدانید چه stateی حذف و چگونه بازیابی می‌شود.

ترتیب استقرار امن

1. روی OS user، VM یا host آزمایشی جدا نصب کنید.
2. یک provider و یک session داشبورد محلی بسازید.
3. ابزار غیرضروری را deny و sandbox محدود را فعال کنید.
4. دستورهای کوتاه بدون secret بنویسید.
5. audit عادی و deep را اجرا کنید.
6. یک channel paired اضافه و دسترسی ناشناس را تست کنید.
7. یک Skill یا plugin مرورشده اضافه و دوباره audit کنید.
8. browser یا node فقط برای workflow مشخص اضافه شود.
9. automation ابتدا draft-only و همراه failure report باشد.
10. لاگ، هزینه، حافظه، approval و side effect بیرونی هفتگی مرور شود.

رفع اشکال

Dashboard باز نمی‌شود: gateway status، health و logs را ببینید و اشغال‌نبودن port را بررسی کنید.

Channel پیام می‌گیرد ولی جواب نمی‌دهد: status، pairing/allowlist، routing، سلامت مدل و dead-letter یا log channel را ببینید.

ایجنت workspace را نمی‌بیند: sandbox scope و workspaceAccess مؤثر را بررسی کنید؛ برای یک مسیر sandbox را global خاموش نکنید.

Automation اجرا نشده: scheduler را از task record جدا کنید و cron، task، timezone، timeout، delivery و approval headless را بررسی کنید.

Audit Gateway باز گزارش می‌کند: bind را localhost یا رابط خصوصی authenticated کنید، احراز هویت قوی بگذارید و تا تکمیل exposure runbook تونل عمومی نسازید.

ایجنت عمل مسدود را تکرار می‌کند: task را متوقف، deny را حفظ و workflow را اصلاح کنید؛ با permission بیشتر به retry پاداش ندهید.

پرسش‌های رایج

آیا OpenClaw یک coding agent است؟

می‌تواند با کد کار و coding agent را یکپارچه کند، اما معماری اصلی آن دستیار شخصی ماندگار و Gateway برای ابزار، دستگاه، پیام و اتوماسیون است.

آیا کاملاً محلی اجرا می‌شود؟

Gateway و ابزار می‌توانند روی دستگاه یا سرور شما باشند؛ inference مدل و سرویس متصل ممکن است راه‌دور باشد.

آیا چند نفر می‌توانند یک instance را مشترک استفاده کنند؟

مدل رسمی امنیت یک مرز اعتماد به‌ازای هر Gateway است. کاربر یا tenant نامطمئن به Gateway و ترجیحاً مرز OS/host جدا نیاز دارد.

آیا sandbox برای bot عمومی کافی است؟

خیر. احراز فرستنده، ابزار محدود، جداسازی credential، کنترل شبکه، channel امن، plugin بازبینی‌شده و monitoring نیز لازم‌اند. پیام و حساب مرورگر خارج sandbox فایل side effect دارند.

آیا standing order را از روز اول فعال کنم؟

پس از قابل‌اعتمادشدن workflow تعاملی، با کار کم‌ریسک و draft-only آغاز کنید. زمان‌بندی بعد از اثبات policy، verification، failure handling و audit اضافه شود.

یادداشت منابع

بازبینی‌شده در ۱۵ مرداد ۱۴۰۵ / ۶ اوت ۲۰۲۶:

• شروع کار
• onboarding خط فرمان
• امنیت Gateway
• sandbox
• مرور automation
• standing orders
• background tasks
• مرجع CLI
• ClawHub
• مخزن رسمی OpenClaw