---
read_when:
    - دستورهای CLI مربوط به ClawHub یا رجیستری OpenClaw ناموفق هستند
    - یک بسته را نمی‌توان نصب، منتشر یا به‌روزرسانی کرد
summary: عیب‌یابی مشکلات ورود به ClawHub، نصب، انتشار، به‌روزرسانی و API.
x-i18n:
    generated_at: "2026-07-27T15:16:55Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: fc789fcc891cf8c44b5d1a10d38a4e6dd4dec9474d8d13f8058ea1c3392a9f91
    source_path: clawhub/troubleshooting.md
    workflow: 16
---

# عیب‌یابی

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

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

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

```bash
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 متغیرهای استاندارد پروکسی را رعایت می‌کند:

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

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

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

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

```bash
clawhub inspect @openclaw/demo
```

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

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

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

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

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

```bash
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 را مدیریت کنید، یک
[ایشوی ادعای سازمان / فضای نام](https://github.com/openclaw/clawhub/issues/new?template=org-namespace-claim.yml)
با مدارک عمومی و غیرحساس باز کنید. برای راهنمای مدارک و مواردی که
نباید در ایشوهای عمومی قرار گیرند، به
[ادعاهای سازمان و فضای نام](/clawhub/namespace-claims) مراجعه کنید.

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

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

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

```bash
clawhub sync --root /path/to/skills
```

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

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

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

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

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

```bash
clawhub update @openclaw/demo --force
```

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

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

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

```bash
openclaw plugins install clawhub:<package>
```

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

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

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

برای جزئیات نقاط پایانی، به [API مبتنی بر HTTP](/clawhub/http-api) مراجعه کنید.