Solución de problemas

clawhub login abre un navegador, pero nunca se completa

La CLI inicia un servidor local de callback de corta duración durante el inicio de sesión en el navegador.

• Asegúrate de que tu navegador pueda acceder a http://127.0.0.1:<port>/callback.
• Revisa las reglas del firewall local, la VPN y el proxy si el callback nunca llega.
• En entornos sin interfaz gráfica, crea un token de API en la interfaz web de ClawHub y ejecuta:

clawhub login --token clh_...

whoami o publish devuelve Unauthorized (401)

• Inicia sesión de nuevo con clawhub login.
• Si usas una ruta de configuración personalizada, confirma que CLAWHUB_CONFIG_PATH apunte al archivo que contiene tu token actual.
• Si usas un token de API, confirma que no haya sido revocado en la interfaz web.

La búsqueda o instalación devuelve Rate limit exceeded (429)

Lee la información de reintento en la respuesta:

• Retry-After: segundos que debes esperar antes de reintentar.
• RateLimit-Limit: el límite aplicado a esta solicitud.
• RateLimit-Remaining: tu presupuesto restante exacto cuando el encabezado está presente. En 429, es 0.
• RateLimit-Reset o X-RateLimit-Reset: momento de reinicio.

Si muchos usuarios comparten una sola IP de salida, los límites de IP anónima pueden alcanzarse aunque cada persona solo envíe unas pocas solicitudes. Inicia sesión cuando sea posible y reintenta después de la demora indicada.

La búsqueda o instalación falla detrás de un proxy

La CLI respeta las variables de proxy estándar:

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

Los nombres admitidos incluyen HTTPS_PROXY, HTTP_PROXY, https_proxy y http_proxy.

Una skill no aparece en la búsqueda

• Revisa el slug exacto o la página del propietario si lo conoces.
• Confirma que la versión sea pública y no esté retenida por escaneo o moderación.
• Si eres propietario de la skill, inicia sesión e inspecciónala:

clawhub inspect @openclaw/demo

Los diagnósticos visibles para el propietario pueden explicar el estado de escaneo, compuerta de carga o moderación.

La publicación falla porque faltan metadatos requeridos

Para skills, revisa el frontmatter de SKILL.md. Las variables de entorno y herramientas requeridas deben declararse para que los usuarios y los escáneres puedan entender el paquete.

Para Plugins, revisa los metadatos de compatibilidad de package.json. Las publicaciones de code-plugin necesitan campos de compatibilidad de OpenClaw como openclaw.compat.pluginApi y openclaw.build.openclawVersion.

Previsualiza primero la carga útil de publicación:

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

La publicación falla con un error de propietario o fuente de GitHub

ClawHub usa la identidad de GitHub y la atribución de origen para conectar los paquetes con sus publicadores.

• Asegúrate de haber iniciado sesión con la cuenta de GitHub propietaria del paquete o autorizada para publicarlo.
• Revisa que la URL de origen sea pública o accesible para ClawHub.
• Para fuentes de GitHub, usa owner/repo, owner/repo@ref o una URL completa de GitHub.

La publicación falla porque un espacio de nombres está reclamado o reservado

Si una publicación falla porque el identificador del propietario, el espacio de nombres de la organización, el ámbito del paquete, el slug de la skill o el nombre del paquete ya está reclamado o reservado, primero confirma que estás publicando con el propietario que coincide con el espacio de nombres. Para paquetes de Plugin, los nombres con ámbito como @example-org/example-plugin deben publicarse como el propietario example-org correspondiente.

Si crees que tu organización, proyecto o marca es el propietario legítimo del espacio de nombres, pero no puedes gestionar el propietario actual de ClawHub, abre un issue de reclamación de organización / espacio de nombres con pruebas públicas y no sensibles. Consulta Reclamaciones de organizaciones y espacios de nombres para obtener orientación sobre pruebas y sobre qué mantener fuera de los issues públicos.

sync dice que no se encontraron skills

sync busca carpetas que contengan SKILL.md o skill.md.

Apúntalo a las raíces que quieras escanear:

clawhub sync --root /path/to/skills

Previsualiza primero si no tienes claro qué se publicará:

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

update se niega por cambios locales

Los archivos locales no coinciden con ninguna versión que ClawHub conozca. Elige una opción:

• Conserva las ediciones locales y omite la actualización.
• Sobrescribe con la versión publicada:

clawhub update @openclaw/demo --force

• Publica tu copia editada como un slug nuevo o un fork.

La instalación de un Plugin falla en OpenClaw

• Usa una fuente explícita de ClawHub:

openclaw plugins install clawhub:<package>

• Revisa la página de detalles del paquete para ver el estado de escaneo y los metadatos de compatibilidad.
• Confirma que tu versión de OpenClaw satisfaga el rango de compatibilidad anunciado por el paquete.
• Si el paquete está oculto, retenido o bloqueado, puede que no sea instalable hasta que el propietario resuelva el problema.

Fallan las solicitudes a la API pública

• Respeta los encabezados de reintento 429 y almacena en caché las respuestas públicas de lista/búsqueda.
• Dirige a los usuarios de vuelta al listado canónico de ClawHub.
• No repliques contenido oculto, privado, retenido o bloqueado por moderación fuera de la superficie de la API pública.

Consulta API HTTP para ver los detalles de los endpoints.