Neura Market Logo

Troubleshooting ClawHub Sign-In, Install, Publish, Update, and API Issues

This page helps ClawHub users resolve common problems with login, authentication, and rate limits. It covers browser callback failures, unauthorized errors, and API rate limiting.

Read this when

  • ClawHub CLI or OpenClaw registry commands fail
  • A package cannot be installed, published, or updated

Troubleshooting

clawhub login opens a browser but never completes

The CLI spins up a short-lived local callback server when you log in through a browser.

  • Verify your browser can reach http://127.0.0.1:<port>/callback.
  • If the callback never arrives, inspect your local firewall, VPN, and proxy settings.
  • In headless environments, generate an API token in the ClawHub web UI and execute:
clawhub login --token clh_...

whoami or publish returns Unauthorized (401)

  • Log in again using clawhub login.
  • If you have a custom config path, make sure CLAWHUB_CONFIG_PATH points to the file holding your current token.
  • When using an API token, verify it has not been revoked in the web UI.

Search or install returns Rate limit exceeded (429)

Read the retry details from the response:

  • Retry-After: number of seconds to wait before retrying.
  • RateLimit-Limit: the limit that was applied to this request.
  • RateLimit-Remaining: your exact remaining budget when the header is present. On 429, it is 0.
  • RateLimit-Reset or X-RateLimit-Reset: reset timing.

When multiple users share a single egress IP, anonymous IP limits may be reached even if each person sends only a few requests. Log in where possible and retry after the reported delay.

Search or install fails behind a proxy

The CLI honors standard proxy variables:

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

Supported names include HTTPS_PROXY, HTTP_PROXY, https_proxy, and http_proxy.

  • If you know the slug or owner page, check it directly.
  • Confirm the release is public and not held by scanning or moderation.
  • If you own the skill, log in and inspect it:
clawhub inspect @openclaw/demo

Owner-visible diagnostics may reveal scan, upload-gate, or moderation status.

Publish fails because required metadata is missing

For skills, check the SKILL.md frontmatter. Required environment variables and tools should be declared so users and scanners can understand the package.

For plugins, check the package.json compatibility metadata. Code-plugin publishes need OpenClaw compatibility fields such as openclaw.compat.pluginApi and openclaw.build.openclawVersion.

Preview the publish payload first:

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

Publish fails with a GitHub owner or source error

ClawHub uses GitHub identity and source attribution to link packages to their publishers.

  • Ensure you are logged in with the GitHub account that owns or can publish the package.
  • Verify the source URL is public or accessible to ClawHub.
  • For GitHub sources, use owner/repo, owner/repo@ref, or a full GitHub URL.

Publish fails because a namespace is claimed or reserved

If a publish fails because the owner handle, org namespace, package scope, skill slug, or package name is already claimed or reserved, first confirm you are publishing with the owner that matches the namespace. For plugin packages, scoped names such as @example-org/example-plugin must be published as the matching example-org owner.

If you believe your org, project, or brand is the rightful namespace owner but you cannot manage the current ClawHub owner, open an Org / Namespace Claim issue with public, non-sensitive proof. See Org and Namespace Claims for evidence guidance and what to keep out of public issues.

sync says no skills were found

sync looks for folders containing SKILL.md or skill.md.

Point it at the roots you want to scan:

clawhub sync --root /path/to/skills

Preview first if you are unsure what will publish:

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

update refuses because of local changes

The local files do not match any version ClawHub knows about. Choose one:

  • Keep local edits and skip the update.
  • Overwrite with the published version:
clawhub update @openclaw/demo --force
  • Publish your edited copy as a new slug or fork.

A plugin install fails in OpenClaw

  • Use an explicit ClawHub source:
openclaw plugins install clawhub:<package>
  • Check the package detail page for scan status and compatibility metadata.
  • Confirm your OpenClaw version satisfies the package's advertised compatibility range.
  • If the package is hidden, held, or blocked, it may not be installable until the owner resolves the issue.

Public API requests fail

  • Respect 429 retry headers and cache public list/search responses.
  • Link users back to the canonical ClawHub listing.
  • Do not mirror hidden, private, held, or moderation-blocked content outside the public API surface.

See HTTP API for endpoint details.