---
x-i18n:
  source_path: "clawhub/troubleshooting.md"
summary: "Troubleshooting ClawHub sign-in, install, publish, sync, update, and API issues."
read_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 starts a short-lived local callback server during browser login.

- Make sure your browser can reach `http://127.0.0.1:<port>/callback`.
- Check local firewall, VPN, and proxy rules if the callback never arrives.
- In headless environments, create an API token in the ClawHub web UI and run:

```bash
clawhub login --token clh_...
```

## `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-Remaining` and `RateLimit-Limit`: your current budget.
- `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.

## Search or install fails behind a proxy

The CLI respects standard proxy variables:

```bash
export HTTPS_PROXY=http://proxy.example.com:3128
clawhub 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:

```bash
clawhub inspect <skill-slug>
```

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:

```bash
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.

## `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:

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

Preview first if you are unsure what will publish:

```bash
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:

```bash
clawhub update <slug> --force
```

- Publish your edited copy as a new slug or fork.

## A plugin install fails in OpenClaw

- Use an explicit ClawHub source:

```bash
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](./http-api.md) for endpoint details.