عیب‌یابی

clawhub login مرورگر را باز می‌کند، اما هرگز کامل نمی‌شود

CLI هنگام ورود از طریق مرورگر، یک سرور بازگشت محلی کوتاه‌عمر راه‌اندازی می‌کند.

• مطمئن شوید مرورگر شما می‌تواند به http://127.0.0.1:<port>/callback دسترسی پیدا کند.
• اگر درخواست بازگشت هرگز نمی‌رسد، قواعد فایروال محلی، VPN و پروکسی را بررسی کنید.
• در محیط‌های بدون رابط گرافیکی، یک توکن API در رابط وب ClawHub ایجاد و دستور زیر را اجرا کنید:

clawhub login --token clh_...

whoami یا publish مقدار Unauthorized (401) را برمی‌گرداند

• با clawhub login دوباره وارد شوید.
• اگر از مسیر پیکربندی سفارشی استفاده می‌کنید، تأیید کنید که CLAWHUB_CONFIG_PATH به فایلی اشاره دارد که حاوی توکن فعلی شما است.
• اگر از توکن API استفاده می‌کنید، تأیید کنید که در رابط وب لغو نشده باشد.

جست‌وجو یا نصب مقدار Rate limit exceeded (429) را برمی‌گرداند

اطلاعات تلاش مجدد را در پاسخ بخوانید:

• Retry-After: تعداد ثانیه‌هایی که باید پیش از تلاش مجدد صبر کنید.
• RateLimit-Limit: محدودیت اعمال‌شده بر این درخواست.
• RateLimit-Remaining: بودجه دقیق باقی‌مانده شما، هنگامی که سرآیند موجود است. در 429، مقدار آن 0 است.
• RateLimit-Reset یا X-RateLimit-Reset: زمان بازنشانی.

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

جست‌وجو یا نصب پشت پروکسی ناموفق است

CLI متغیرهای استاندارد پروکسی را رعایت می‌کند:

export HTTPS_PROXY=http://proxy.example.com:3128clawhub search "my query"

نام‌های پشتیبانی‌شده شامل HTTPS_PROXY، HTTP_PROXY، https_proxy و http_proxy هستند.

یک مهارت در جست‌وجو ظاهر نمی‌شود

• اگر نامک دقیق یا صفحه مالک را می‌دانید، آن را بررسی کنید.
• تأیید کنید که انتشار عمومی است و به‌دلیل اسکن یا نظارت متوقف نشده است.
• اگر مالک مهارت هستید، وارد شوید و آن را بررسی کنید:

clawhub inspect @openclaw/demo

اطلاعات تشخیصی قابل‌مشاهده برای مالک ممکن است وضعیت اسکن، دروازه بارگذاری یا نظارت را توضیح دهد.

انتشار به‌دلیل نبود فراداده الزامی ناموفق است

برای مهارت‌ها، frontmatter فایل SKILL.md را بررسی کنید. متغیرهای محیطی و ابزارهای الزامی باید اعلام شوند تا کاربران و اسکنرها بتوانند بسته را درک کنند.

برای Pluginها، فراداده سازگاری package.json را بررسی کنید. انتشار Pluginهای کد به فیلدهای سازگاری OpenClaw مانند openclaw.compat.pluginApi و openclaw.build.openclawVersion نیاز دارد.

ابتدا پیش‌نمایش محموله انتشار را مشاهده کنید:

clawhub package publish <source> --family code-plugin --dry-run

انتشار با خطای مالک یا منبع GitHub ناموفق است

ClawHub برای مرتبط‌کردن بسته‌ها با ناشرانشان از هویت GitHub و انتساب منبع استفاده می‌کند.

• مطمئن شوید با حساب GitHub که مالک بسته است یا اجازه انتشار آن را دارد، وارد شده‌اید.
• بررسی کنید که URL منبع عمومی یا برای ClawHub قابل‌دسترسی باشد.
• برای منابع GitHub، از owner/repo، owner/repo@ref یا یک URL کامل GitHub استفاده کنید.

انتشار به‌دلیل ادعاشده یا رزروشده بودن یک فضای نام ناموفق است

اگر انتشار به این دلیل ناموفق است که شناسه مالک، فضای نام سازمان، محدوده بسته، نامک مهارت یا نام بسته از قبل ادعا یا رزرو شده است، ابتدا تأیید کنید که انتشار را با مالکی انجام می‌دهید که با فضای نام مطابقت دارد. برای بسته‌های Plugin، نام‌های محدوده‌دار مانند @example-org/example-plugin باید با مالک مطابق example-org منتشر شوند.

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

sync می‌گوید هیچ مهارتی پیدا نشد

sync پوشه‌های حاوی SKILL.md یا skill.md را جست‌وجو می‌کند.

آن را به ریشه‌هایی که می‌خواهید اسکن شوند هدایت کنید:

clawhub sync --root /path/to/skills

اگر مطمئن نیستید چه چیزی منتشر خواهد شد، ابتدا پیش‌نمایش را مشاهده کنید:

clawhub sync --all --dry-run --no-input

update به‌دلیل تغییرات محلی از ادامه خودداری می‌کند

فایل‌های محلی با هیچ نسخه‌ای که ClawHub می‌شناسد مطابقت ندارند. یکی را انتخاب کنید:

• ویرایش‌های محلی را نگه دارید و از به‌روزرسانی صرف‌نظر کنید.
• با نسخه منتشرشده بازنویسی کنید:

clawhub update @openclaw/demo --force

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

نصب یک Plugin در OpenClaw ناموفق است

• از یک منبع صریح ClawHub استفاده کنید:

openclaw plugins install clawhub:<package>

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

درخواست‌های API عمومی ناموفق هستند

• سرآیندهای تلاش مجدد 429 را رعایت و پاسخ‌های عمومی فهرست/جست‌وجو را کش کنید.
• کاربران را به فهرست رسمی ClawHub پیوند دهید.
• محتوای پنهان، خصوصی، متوقف یا مسدودشده توسط نظارت را خارج از سطح API عمومی بازنشر نکنید.

برای جزئیات نقاط پایانی، به API مبتنی بر HTTP مراجعه کنید.