Troubleshooting

clawhub login waits for authorization

Open the verification URL printed by the CLI, sign in with GitHub if needed, and select Authorize for the displayed code. You can use a browser on another device; no localhost callback is required.

If the code expires, run clawhub login again. For unattended login, create an API token in ClawHub Settings → API tokens and run:

clawhub login --token <token>

whoami or publish returns Unauthorized (401)

• Sign in again with clawhub login.
• If you use a custom config path, confirm CLAWHUB_CONFIG_PATH points at the file that contains your current token.
• If you use an API token, confirm it was not revoked in the web UI.

Search or install returns Rate limit exceeded (429)

Read the retry information in the response:

• Retry-After: seconds to wait before retrying.
• RateLimit-Limit: the limit 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.

If many users share one egress IP, anonymous IP limits can be hit even when each person only sends a few requests. Sign in where possible and retry after the reported delay.

Only a real 429 carries these headers, and the CLI shows a reset hint only for a 429. Other failures are not rate limiting.

Publish returns ClawHub backend is temporarily unavailable (503)

The registry hit a temporary backend failure, such as overload or write contention. The request was not rejected for validation. The CLI already retried it with backoff, honoring the server's Retry-After. Run the command again shortly. If a retry reports that the version already exists, an earlier attempt completed; check the published version before bumping it.

If the same failure arrives as 409 saying the request cannot be retried, it happened after the publish saved its uploaded files. Check whether the version was published; if not, run clawhub publish again to upload the files again.

Search or install fails behind a proxy

The CLI respects standard proxy variables:

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

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

A skill does not appear in search

• Check the exact slug or owner page if you know it.
• Confirm the release is public and not held by scan or moderation.
• If you own the skill, sign in and inspect it:

clawhub inspect @openclaw/demo

Owner-visible diagnostics may explain scan, upload-gate, or moderation state.

Publish fails because required metadata is missing

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

For plugins, check 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 connect packages to their publishers.

• Make sure you are signed in with the GitHub account that owns or can publish the package.
• Check that 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 that 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 the explicit ClawHub source on released OpenClaw versions through 2026.10.4. This form also works on updated builds:

openclaw plugins install clawhub:<package>

• Prefix-free commands require an updated main/dev build with ClawHub-default support. On older versions, a bare package name can select npm instead.
• If the plugin is only available on npm, use openclaw plugins install npm:<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.