CLI commands
کانالها
openclaw channels
حسابهای کانال چت و وضعیت زمان اجرای آنها را در Gateway مدیریت کنید.
مستندات مرتبط:
فرمانهای رایج
openclaw channels listopenclaw channels list --allopenclaw channels statusopenclaw channels capabilitiesopenclaw channels capabilities --channel discord --target channel:123openclaw channels resolve --channel slack "#general" "@jane"openclaw channels logs --channel allopenclaw channels dead-letters list --channel telegram --account defaultchannels list فقط کانالهای چت را نمایش میدهد: بهطور پیشفرض حسابهای پیکربندیشده، همراه با برچسبهای وضعیت installed، configured و enabled برای هر حساب (--json برای خروجی ماشینی). برای نمایش کانالهای همراهی که هنوز حسابی برایشان پیکربندی نشده و کانالهای قابلنصب کاتالوگ که هنوز روی دیسک نیستند، --all را ارسال کنید. احراز هویت ارائهدهنده و میزان استفاده از مدل در بخشهای دیگری قرار دارند: openclaw models auth list برای پروفایلهای احراز هویت ارائهدهنده و openclaw status یا openclaw models list برای میزان استفاده/سهمیه.
وضعیت / قابلیتها / تفکیک / گزارشها
channels status:--channel <name>،--probe،--timeout <ms>(پیشفرض10000)،--jsonchannels capabilities:--channel <name>،--account <id>(نیازمند--channel)،--target <dest>(نیازمند--channel)،--timeout <ms>(پیشفرض10000، با سقف30000)،--jsonchannels resolve <entries...>:--channel <name>،--account <id>،--kind <auto|user|group>(پیشفرضauto)،--jsonchannels logs:--channel <name|all>(پیشفرضall)،--lines <n>(پیشفرض200)،--json
channels status --probe مسیر زنده است: در یک Gateway قابلدسترسی، بررسیهای
probeAccount برای هر حساب و بررسیهای اختیاری auditAccount را اجرا میکند؛ بنابراین خروجی میتواند شامل وضعیت
انتقال و نتایج کاوش، مانند works، probe failed، audit ok یا audit failed باشد.
اگر Gateway در دسترس نباشد، channels status بهجای خروجی کاوش زنده،
خلاصههای صرفاً مبتنی بر پیکربندی را نمایش میدهد.
نامههای مرده ورودی
رویدادهای ورودی که سیاست تلاش مجدد خود را تمام میکنند، برای دوره نگهداری کنونی ورودیهای ناموفق صف در پایگاه داده وضعیت مشترک باقی میمانند. یک حساب کانال را با فرمانهای زیر بررسی کنید:
openclaw channels dead-letters list --channel telegram --account defaultopenclaw channels dead-letters list --channel telegram --account default --jsonنمای متنی شناسههای رویداد، دلایل شکست، تعداد تلاشها و مدتزمان گذشته از شکست را نمایش میدهد. خروجی JSON برای عیبیابی، محتوای نگهداریشده، فراداده، مسیر و برچسبهای زمانی تلاشها را نیز شامل میشود.
پس از رفع مشکل زیربنایی، یک رویداد را با شناسه اصلی آن دوباره در صف قرار دهید:
openclaw channels dead-letters resubmit <event-id> --channel telegram --account defaultاین فرمانها را روی میزبان Gateway اجرا کنید تا به همان پایگاه داده وضعیت مشترکی دسترسی داشته باشند که زمان اجرای کانال استفاده میکند. ارسال مجدد، محتوا، فراداده و مسیر را حفظ میکند، اما شمارنده تلاش و عمر صف را بازنشانی میکند. این عملیات نشانگر شکست آن رویداد را بهصورت اتمی جایگزین میکند؛ بنابراین تکرار فرمان هنگامی که رویداد در انتظار یا دریافتشده است، بهجای ایجاد ارسال دوم رد میشود. کانال در حال اجرا آن را در تخلیه ورودی بعدی خود دریافت میکند. رویدادهای تکمیلشده نهایی باقی میمانند و نمیتوان آنها را دوباره ارسال کرد. ردیفهای ناموفقی که پیش از افزودهشدن قابلیت نگهداری محتوا ایجاد شدهاند، ممکن است همچنان در فهرست ظاهر شوند، اما ارسال مجدد آنها رد میشود، زیرا محتوایشان در دسترس نیست.
openclaw health تعداد نامههای مرده و عمر قدیمیترین شکست را برای هر حساب کانال گزارش میکند. openclaw doctor حسابهای تحتتأثیر را نام میبرد و به فرمان بررسی ارجاع میدهد.
از openclaw sessions، sessions.list در Gateway یا ابزار
sessions_list عامل بهعنوان نشانگر سلامت سوکت کانال استفاده نکنید. این سطوح،
ردیفهای ذخیرهشده مکالمه را گزارش میکنند، نه وضعیت زمان اجرای ارائهدهنده. پس از راهاندازی مجدد ارائهدهنده Discord،
ممکن است حسابی متصل اما بدون فعالیت سالم باشد، درحالیکه تا رویداد ورودی یا خروجی بعدی مکالمه،
هیچ ردیف نشست Discord ظاهر نمیشود.
افزودن / حذف حسابها
openclaw channels add --channel telegram --token <bot-token>openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"openclaw channels remove --channel telegram --deletechannels remove فقط روی Pluginهای کانال نصبشده/پیکربندیشده عمل میکند. برای کانالهای قابلنصب کاتالوگ، ابتدا از channels add استفاده کنید. بدون --delete، برای غیرفعالکردن حساب پرسش میکند و پیکربندی آن را نگه میدارد؛ --delete ورودیهای پیکربندی را بدون پرسش حذف میکند.
برای Pluginهای کانال متکی به زمان اجرا، channels remove همچنین از Gateway در حال اجرا میخواهد پیش از بهروزرسانی پیکربندی، حساب انتخابشده را متوقف کند تا غیرفعال یا حذفکردن حساب باعث نشود شنونده قدیمی تا زمان راهاندازی مجدد فعال بماند.
پوش کنترل مشترک فقط شامل --channel، --account و نمایش اختیاری حساب --name است. هر Plugin مدرن کانال، اعتبارنامه، انتقال و معنای ویژه ارائهدهنده خود را مدیریت میکند. پس از انتخاب کانال با شناسه موقعیتی یا --channel <id>، CLI فقط گزینههای همان کانال را از فراداده بسته Plugin همراه یا نصبشده میسازد، بدون آنکه کد زمان اجرای کانال را بارگذاری کند.
پرچمهایی با ظاهر مشترک، مانند --token، --url یا --use-env، هنگامی که یک قرارداد مدرن آنها را مدیریت میکند همچنان متعلق به کانال هستند. اگر Plugin شخص ثالث انتخابشده همچنان از سازگارگر قدیمی راهاندازی مشترک استفاده کند، هسته مجموعه پرچمهای سازگاری منتشرشده را فقط برای همان کانال، همراه با cliAddOptions قدیمی آن ثبت میکند. فیلدهای قدیمی نامرتبط به کانالهای دیگر نشت نمیکنند و کانال مدرن انتخابشده، پرچمهای سازگاری اعلامنشده را رد میکند.
نمونههایی از پرچمهای متعلق به کانال عبارتاند از:
| کانال | پرچمها |
|---|---|
| Google Chat | --webhook-path، --webhook-url، --audience-type، --audience |
| iMessage | --cli-path، --db-path، --service، --region |
| Matrix | --homeserver، --user-id، --access-token، --password، --device-name، --initial-sync-limit |
| Nostr | --private-key، --relay-urls |
| Signal | --signal-number، --signal-transport، --cli-path، --http-url، --http-host، --http-port |
| Tlon | --ship، --url، --code، --group-channels، --dm-allowlist، --auto-discover-channels |
--auth-dir |
اگر هنگام اجرای فرمان افزودن مبتنی بر پرچم نیاز باشد Plugin کانال نصب شود، OpenClaw بدون بازکردن اعلان تعاملی نصب Plugin، از منبع نصب پیشفرض کانال استفاده میکند.
راهاندازی هدایتشده و راهاندازی مبتنی بر پرچم، هر دو از تجزیهگر، اعتبارسنجی، تفکیک حساب، نویسنده پیکربندی و قلابهای پس از نوشتن کانال انتخابشده عبور میکنند. پرچمهای پشتیبانینشده بهجای پذیرفتهشدن از طریق یک مجموعه ورودی سراسری، با خطای راهاندازی کانال مالک شکست میخورند.
هنگامی که openclaw channels add را بدون پرچم مستقیم حساب، اعتبارنامه یا پیکربندی کانال اجرا میکنید، جادوگر تعاملی میتواند پرسش نمایش دهد. شناسه موقعیتی کانال و --channel <id> هر دو آن کانال را از پیش انتخاب میکنند، بدون آنکه راهنمایی را دور بزنند:
openclaw channels add telegramopenclaw channels add --channel telegramجادوگر میتواند موارد زیر را درخواست کند:
- شناسههای حساب برای هر کانال انتخابشده
- نامهای نمایشی اختیاری برای آن حسابها
Route these channel accounts to agents now?
اگر اتصال فوری را تأیید کنید، جادوگر میپرسد کدام عامل باید مالک هر حساب کانال پیکربندیشده باشد و اتصالهای مسیریابی با دامنه حساب را مینویسد.
همچنین میتوانید همین قواعد مسیریابی را بعداً با openclaw agents bindings، openclaw agents bind و openclaw agents unbind مدیریت کنید (به عاملها مراجعه کنید).
هنگامی که حسابی غیرپیشفرض را به کانالی اضافه میکنید که همچنان از تنظیمات سطح بالای تکحسابی استفاده میکند، OpenClaw پیش از نوشتن حساب جدید، آن مقادیر سطح بالا را به نگاشت حسابهای کانال ارتقا میدهد. اگر کانال دقیقاً یک حساب نامگذاریشده داشته باشد یا defaultAccount به یکی اشاره کند، ارتقا همان حساب موجود را دوباره استفاده میکند؛ در غیر این صورت، مقادیر در channels.<channel>.accounts.default قرار میگیرند.
رفتار مسیریابی سازگار باقی میماند:
- اتصالهای موجودِ صرفاً مبتنی بر کانال (بدون
accountId) همچنان با حساب پیشفرض مطابقت دارند. channels addدر حالت غیرتعاملی اتصالها را بهطور خودکار ایجاد یا بازنویسی نمیکند.- راهاندازی تعاملی میتواند بهصورت اختیاری اتصالهای با دامنه حساب را اضافه کند.
اگر پیکربندی از قبل در وضعیت ترکیبی قرار داشته است (حسابهای نامگذاریشده موجودند و مقادیر تکحسابی سطح بالا همچنان تنظیم شدهاند)، openclaw doctor --fix را اجرا کنید تا مقادیر با دامنه حساب به حساب ارتقایافته انتخابشده برای آن کانال منتقل شوند.
ورود و خروج (تعاملی)
openclaw channels login --channel whatsappopenclaw channels logout --channel whatsappchannels loginاز--account <id>و--verboseپشتیبانی میکند؛channels logoutاز--account <id>پشتیبانی میکند.channels loginوlogoutمیتوانند هنگامی که فقط یک کانال پیکربندیشده از آن اقدام پشتیبانی میکند، کانال را استنباط کنند؛ اگر چندین کانال وجود دارد،--channelرا ارسال کنید.channels logoutدر صورت دردسترسبودن، مسیر زنده Gateway را ترجیح میدهد تا خروج پیش از پاککردن وضعیت احراز هویت کانال، هر شنونده فعال را متوقف کند. اگر Gateway محلی در دسترس نباشد، به پاکسازی محلی احراز هویت بازمیگردد؛ باgateway.mode: "remote"، خطای Gateway باعث شکست فرمان میشود.- پس از ورود موفق، CLI از Gateway محلی قابلدسترسی میخواهد حساب را راهاندازی کند؛ در حالت دوردست، احراز هویت را بهصورت محلی ذخیره میکند و یادآور میشود که زمان اجرای دوردست دوباره راهاندازی نشده است.
channels loginرا از ترمینالی روی میزبان Gateway اجرا کنید.execعامل این جریان ورود تعاملی را مسدود میکند؛ در صورت وجود، ابزارهای ورود عامل بومی کانال، مانندwhatsapp_login، باید از داخل چت استفاده شوند.
عیبیابی
- برای کاوش گسترده،
openclaw status --deepرا اجرا کنید. - برای رفع هدایتشده مشکلات، از
openclaw doctorاستفاده کنید. - هنگامی که Gateway در دسترس نباشد،
openclaw channels statusبه خلاصههای صرفاً مبتنی بر پیکربندی بازمیگردد. اگر اعتبارنامه کانالی پشتیبانیشده از طریق SecretRef پیکربندی شده، اما در مسیر فرمان جاری در دسترس نباشد، آن حساب را پیکربندیشده همراه با یادداشتهای تنزل وضعیت گزارش میکند، نه اینکه آن را پیکربندینشده نمایش دهد.
کاوش قابلیتها
راهنمای قابلیتهای ارائهدهنده (هدفها/دامنهها در صورت وجود) را همراه با پشتیبانی ایستای ویژگیها دریافت کنید:
openclaw channels capabilitiesopenclaw channels capabilities --channel discord --target channel:123یادداشتها:
--channelاختیاری است؛ برای فهرستکردن همه کانالها (از جمله کانالهای ارائهشده توسط Plugin) آن را حذف کنید.--accountفقط همراه با--channelمعتبر است.--targetمقدارchannel:<id>یا شناسه عددی خام یک کانال را میپذیرد و فقط برای Discord کاربرد دارد. برای کانالهای صوتی Discord، بررسی مجوز، نبودViewChannel،Connect،Speak،SendMessagesوReadMessageHistoryرا علامتگذاری میکند.- کاوشها مختص ارائهدهنده هستند: هویت ربات Discord و intentها، بههمراه مجوزهای اختیاری کانال؛ ربات Slack و دامنههای کاربر؛ پرچمهای ربات Telegram و Webhook؛ نسخه دیمون Signal؛ توکن برنامه Microsoft Teams و نقشها/دامنههای Graph (در موارد شناختهشده همراه با یادداشت). کانالهای فاقد کاوش،
Probe: unavailableرا گزارش میکنند.
تبدیل نامها به شناسهها
نام کانالها/کاربران را با استفاده از فهرست راهنمای ارائهدهنده به شناسه تبدیل کنید:
openclaw channels resolve --channel slack "#general" "@jane"openclaw channels resolve --channel discord "My Server/#support" "@someone"openclaw channels resolve --channel matrix "Project Room"نکتهها:
- برای اجبار نوع هدف، از
--kind user|group|autoاستفاده کنید. - هنگامی که چند ورودی نام یکسانی دارند، فرایند تبدیل، تطابقهای فعال را ترجیح میدهد.
channels resolveفقط خواندنی است. اگر حساب انتخابشده از طریق SecretRef پیکربندی شده باشد، اما آن اعتبارنامه در مسیر فرمان فعلی در دسترس نباشد، فرمان بهجای لغو کل اجرا، نتایج حلنشده و تنزلیافته را همراه با یادداشتها برمیگرداند.channels resolvePluginهای کانال را نصب نمیکند. پیش از تبدیل نامهای یک کانال قابلنصب از کاتالوگ، ازchannels add --channel <name>استفاده کنید.
