Troubleshooting ClawHub Login, Install, Publish, Update, and API Issues

Troubleshooting

clawhub login opens a browser but never completes

When logging in through a browser, the CLI starts a short-lived local callback server.

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

clawhub login --token clh_...

whoami or publish returns Unauthorized (401)

• Reauthenticate using clawhub login.
• When using a custom configuration path, ensure CLAWHUB_CONFIG_PATH references the file holding your current token.
• If working with an API token, verify it hasn't been revoked through the web UI.

Search or install returns Rate limit exceeded (429)

Examine the retry details included in the response:

• Retry-After: number of seconds to wait before attempting again.
• RateLimit-Limit: the rate limit enforced on this request.
• RateLimit-Remaining: your remaining allowance at the moment the header appears. On 429, this value is 0.
• RateLimit-Reset or X-RateLimit-Reset: when the rate limit resets.

When several users share a single egress IP, anonymous IP limits may be reached even if each individual sends only a few requests. Where possible, sign in and retry after the delay indicated.

Search or install fails behind a proxy

The CLI respects standard proxy environment variables:

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

Recognized variable names include HTTPS_PROXY, HTTP_PROXY, https_proxy, and http_proxy.

A skill does not appear in search

• If you know the slug or owner page, check it directly.
• Verify the release is public and not delayed by scanning or moderation.
• For skills you own, sign in and inspect with:

clawhub inspect @openclaw/demo

Diagnostics visible to the owner may reveal scan, upload-gate, or moderation status.

Publish fails because required metadata is missing

For skills, review the SKILL.md frontmatter. Declare required environment variables and tools so users and scanners understand the package.

For plugins, examine the package.json compatibility metadata. Code-plugin publishes require OpenClaw compatibility fields like openclaw.compat.pluginApi and openclaw.build.openclawVersion to be present.

First preview the publish payload:

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 signed in with the GitHub account that owns or is authorized to publish the package.
• Confirm the source URL is public or reachable by ClawHub.
• For GitHub sources, provide 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 taken or reserved, first verify that you are publishing as the owner matching the namespace. For plugin packages, scoped names like @example-org/example-plugin must be published under the corresponding example-org owner.

If you believe your org, project, or brand is the rightful namespace owner but cannot manage the current ClawHub owner, open an Org / Namespace Claim issue with public, non-sensitive evidence. Refer to Org and Namespace Claims for guidance on what evidence to provide and what to avoid posting publicly.

sync says no skills were found

sync searches for directories containing SKILL.md or skill.md.

Point it at the root directories you want to scan:

clawhub sync --root /path/to/skills

If you are uncertain what will be published, preview first:

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

update refuses because of local changes

The local files do not correspond to any version ClawHub recognizes. Choose an option:

• Keep your local changes and skip the update.
• Replace with the published version:

clawhub update @openclaw/demo --force

• Publish your modified copy as a new slug or fork.

A plugin install fails in OpenClaw

• Specify an explicit ClawHub source:

openclaw plugins install clawhub:<package>

• Visit the package detail page to review scan status and compatibility metadata.
• Confirm that your OpenClaw version falls within 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

• Honor 429 retry headers and cache public list/search responses.
• Direct users 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 documentation.