openclaw agent

یک نوبت عامل را از طریق Gateway اجرا کنید. پرچم صریح --local تنها مسیر اجرای تعبیه‌شده است.

حداقل یک انتخاب‌گر نشست ارائه کنید: --to، --session-key، --session-id یا --agent.

مرتبط: ابزار ارسال عامل

گزینه‌ها

• -m, --message <text>: بدنه پیام
• --message-file <path>: خواندن بدنه پیام از یک فایل UTF-8
• -t, --to <dest>: گیرنده‌ای که برای استخراج کلید نشست استفاده می‌شود
• --session-key <key>: کلید صریح نشست برای استفاده در مسیریابی
• --session-id <id>: شناسه صریح نشست
• --agent <id>: شناسه عامل؛ پیوندهای مسیریابی را نادیده می‌گیرد
• --model <id>: جایگزینی مدل برای این اجرا (provider/model یا شناسه مدل)
• --thinking <level>: سطح تفکر عامل (off، minimal، low، medium، high، به‌علاوه سطوح سفارشی پشتیبانی‌شده توسط ارائه‌دهنده مانند xhigh، adaptive یا max)
• --verbose <on|off>: ماندگار کردن سطح جزئیات برای نشست
• --channel <channel>: کانال تحویل؛ برای استفاده از کانال اصلی نشست، آن را حذف کنید
• --reply-to <target>: جایگزینی مقصد تحویل
• --reply-channel <channel>: جایگزینی کانال تحویل
• --reply-account <id>: جایگزینی حساب تحویل
• --local: اجرای مستقیم عامل تعبیه‌شده (پس از پیش‌بارگذاری رجیستری Plugin)
• --deliver: ارسال پاسخ به کانال/مقصد انتخاب‌شده
• --timeout <seconds>: جایگزینی مهلت نوبت عامل برای این فرمان (پیش‌فرض 600 یا agents.defaults.timeoutSeconds)؛ 0 مهلت کلی را غیرفعال می‌کند. مقدار جایگزین 600 ثانیه متعلق به این فرمان CLI است، نه نوبت‌های عادی Gateway که پیش‌فرضشان 48 ساعت است.
• --json: خروجی JSON

مثال‌ها

openclaw agent --to +15555550123 --message "به‌روزرسانی وضعیت" --deliveropenclaw agent --agent ops --message "گزارش‌های ثبت‌شده را خلاصه کن"openclaw agent --agent ops --message-file ./task.mdopenclaw agent --agent ops --model openai/gpt-5.4 --message "گزارش‌های ثبت‌شده را خلاصه کن"openclaw agent --session-key agent:ops:incident-42 --message "وضعیت را خلاصه کن"openclaw agent --agent ops --session-key incident-42 --message "وضعیت را خلاصه کن"openclaw agent --session-id 1234 --message "صندوق ورودی را خلاصه کن" --thinking mediumopenclaw agent --to +15555550123 --message "ردیابی گزارش‌های ثبت‌شده" --verbose on --jsonopenclaw agent --agent ops --message "گزارش را تولید کن" --deliver --reply-channel slack --reply-to "#reports"openclaw agent --agent ops --message "به‌صورت محلی اجرا کن" --local

نکته‌ها

• دقیقاً یکی از --message یا --message-file را ارائه کنید. --message-file نشان BOM ابتدایی UTF-8 را حذف و محتوای چندخطی را حفظ می‌کند؛ فایل‌هایی را که UTF-8 معتبر نیستند رد می‌کند. فایل‌های بزرگ‌تر از 4 MiB پیش از ارسال رد می‌شوند.
• فرمان‌های اسلش (برای مثال /compact) را نمی‌توان از طریق --message اجرا کرد. CLI آن‌ها را رد می‌کند و در عوض شما را به فرمان اختصاصی هدایت می‌کند (openclaw sessions compact <key> برای Compaction).
• اجراهای --local یک‌باره‌اند: منابع بازگشتی MCP بسته‌بندی‌شده و نشست‌های گرم stdio مربوط به Claude که برای اجرا باز شده‌اند، پس از پاسخ خاتمه می‌یابند تا فراخوانی‌های اسکریپتی هیچ فرایند فرزند محلی در حال اجرایی باقی نگذارند. اجراهای مبتنی بر Gateway در عوض منابع بازگشتی MCP تحت مالکیت Gateway را در فرایند در حال اجرای Gateway نگه می‌دارند.
• اجرای مستقل تعبیه‌شده با --local تا زمانی که بازیابی پس از راه‌اندازی مجدد در انتظار است، از استفاده مجدد نشست اصلی موجود خودداری می‌کند. نوبت را از طریق یک Gateway سالم اجرا کنید یا آن را در همان‌جا با /new یا /reset بازنشانی کنید؛ یک فرایند تعبیه‌شده مستقل نمی‌تواند مالک آن بازیابی را به‌طور ایمن با اسکنر Gateway هماهنگ کند.
• هنگام استفاده هم‌زمان از --agent، --channel و --to، مسیریابی نشست از گیرنده متعارف کانال و session.dmScope پیروی می‌کند. کانال‌هایی که هویت گیرنده پایدار و فقط خروجی دارند، از نشستی تحت مالکیت ارائه‌دهنده استفاده می‌کنند که از نشست اصلی عامل جداست. --reply-channel و --reply-account فقط بر تحویل اثر می‌گذارند.
• --session-key یک کلید صریح نشست را انتخاب می‌کند. کلیدهای دارای پیشوند عامل باید از agent:<agent-id>:<session-key> استفاده کنند و اگر هر دو ارائه شوند، --agent باید با شناسه عامل کلید مطابقت داشته باشد. کلیدهای ساده و غیرنگهبان، در صورت ارائه --agent به آن محدود می‌شوند؛ در غیر این صورت به عامل پیش‌فرض پیکربندی‌شده محدود خواهند شد؛ برای مثال --agent ops --session-key incident-42 به agent:ops:incident-42 مسیریابی می‌شود. کلیدهای تحت‌اللفظی global و unknown فقط وقتی هیچ --agent ارائه نشده باشد، بدون محدوده باقی می‌مانند.
• --json خروجی استاندارد را برای پاسخ JSON رزرو می‌کند؛ اطلاعات عیب‌یابی Gateway، Plugin و --local به خطای استاندارد می‌روند تا اسکریپت‌ها بتوانند خروجی استاندارد را مستقیماً تجزیه کنند.
• پس از پایان یافتن تلاش‌های مجدد گذرای دست‌دهی، پایان مهلت Gateway یا بسته شدن اتصال باعث شکست فرمان می‌شود؛ CLI هرگز نوبت را بی‌سروصدا به‌صورت تعبیه‌شده دوباره اجرا نمی‌کند. قطع انتقال مبهم است — ممکن است Gateway نوبت را پذیرفته باشد و همچنان آن را به پایان برساند — بنابراین راهنمای خطای استاندارد توصیه می‌کند پیش از تلاش مجدد یا اجرای دوباره با --local، برای جلوگیری از اجرای دوباره نوبت، openclaw gateway status و رونوشت نشست را بررسی کنید.
• SIGTERM/SIGINT یک درخواست در حال انتظار مبتنی بر Gateway را متوقف می‌کنند؛ اگر Gateway از قبل اجرا را پذیرفته باشد، CLI پیش از خروج برای شناسه آن اجرا chat.abort را نیز ارسال می‌کند. اجراهای --local همان سیگنال را دریافت می‌کنند، اما chat.abort را ارسال نمی‌کنند. فرایند فرزند راه‌انداز که با نخستین SIGINT یا SIGTERM هدایت‌شده خاتمه یابد، به‌ترتیب با وضعیت 130 یا 143 خارج می‌شود. اگر کلید داخلی حذف اجرای تکراری از قبل برای این نشست اجرای فعالی داشته باشد، پاسخ status: "in_flight" را گزارش می‌کند و CLI غیر JSON به‌جای پاسخ خالی، اطلاعات عیب‌یابی را در خطای استاندارد چاپ می‌کند. برای پوشش‌دهنده‌های خارجی cron/systemd، یک راهکار پشتیبان برای پایان اجباری مانند timeout -k 60 600 openclaw agent ... نگه دارید تا اگر خاموش‌شدن نتواند عملیات را تخلیه کند، ناظر بتواند فرایند را جمع‌آوری کند.
• هنگامی که این فرمان بازتولید models.json را فعال می‌کند، اعتبارنامه‌های ارائه‌دهنده که با SecretRef مدیریت می‌شوند، به‌صورت نشانگرهای غیرمحرمانه (برای مثال نام متغیرهای محیطی، secretref-env:ENV_VAR_NAME یا secretref-managed) ماندگار می‌شوند و هرگز به متن ساده محرمانه تبدیل نمی‌شوند. نوشتن نشانگرها از عکس فوری پیکربندی منبع فعال انجام می‌شود، نه از مقادیر محرمانه حل‌شده زمان اجرا.

وضعیت تحویل JSON

با --json --deliver، پاسخ JSON در CLI شامل deliveryStatus در سطح بالا است تا اسکریپت‌ها بتوانند ارسال‌های تحویل‌شده، سرکوب‌شده، جزئی و ناموفق را از هم تشخیص دهند:

{  "payloads": [{ "text": "گزارش آماده است", "mediaUrl": null }],  "meta": { "durationMs": 1200 },  "deliveryStatus": {    "requested": true,    "attempted": true,    "status": "sent",    "succeeded": true,    "resultCount": 1  }}

پاسخ‌های CLI مبتنی بر Gateway همچنین شکل خام نتیجه Gateway را در result.deliveryStatus حفظ می‌کنند.

deliveryStatus.status یکی از موارد زیر است:

فیلدهای رایج:

• requested: هنگام وجود شیء، همیشه true است.
• attempted: پس از اجرای مسیر ارسال ماندگار، true است؛ برای شکست‌های بررسی پیش از اجرا یا نبود بارِ داده قابل‌مشاهده، false است.
• succeeded: true، false یا "partial"؛ "partial" با status: "partial_failed" همراه است.
• reason: دلیل با حروف کوچک و قالب snake-case از تحویل ماندگار یا اعتبارسنجی پیش از اجرا. مقادیر شناخته‌شده شامل cancelled_by_message_sending_hook، no_visible_payload، no_visible_result، channel_resolved_to_internal، unknown_channel، invalid_delivery_target و no_delivery_target هستند؛ ارسال‌های ماندگار ناموفق ممکن است مرحله ناموفق را نیز گزارش کنند. مقادیر ناشناخته را مبهم در نظر بگیرید، زیرا این مجموعه می‌تواند گسترش یابد.
• resultCount: تعداد نتایج ارسال کانال، در صورت موجود بودن.
• sentBeforeError: اگر در شکست جزئی، حداقل یک بارِ داده پیش از بروز خطا ارسال شده باشد، true است.
• error: برای ارسال‌های ناموفق یا دارای شکست جزئی، true است.
• errorMessage: فقط زمانی وجود دارد که پیام خطای زیربنایی تحویل ثبت شده باشد. شکست‌های پیش از اجرا دارای error/reason هستند، اما errorMessage ندارند.
• payloadOutcomes: نتایج اختیاری برای هر بارِ داده، همراه با index، status، reason، resultCount، error، stage، sentBeforeError یا فراداده هوک، در صورت موجود بودن.

مرتبط

• مرجع CLI
• زمان اجرای عامل