skillhub/docs/openclaw-integration-en.md

OpenClaw Integration Guide

This document explains how to configure the ClawHub CLI to connect to a private SkillHub registry for search, inspection, and installation. Use the first-party SkillHub CLI for publishing.

Not only applicable to Openclaw, but also compatible with other CLI Coding Agents (Claude Code, OpenCode, Qcoder, etc.) or Agent assistants (Nanobot, CoPaw, etc.) by specifying the installation directory.

Overview

SkillHub provides a ClawHub-compatible API for common read and install flows. With simple configuration, you can:

• 🔍 Search for private skills within your organization
• 📥 Download and install skill packages
• ⭐ Star skills

Current compatibility boundaries:

• ClawHub CLI 0.23.3 uses /api/v1/whoami, which matches the SkillHub compatibility API.
• ClawHub publishing depends on upload-ticket endpoints that SkillHub does not implement, so clawhub publish and clawhub sync are not supported.
• ClawHub CLI 0.23.3 does not reliably prioritize the private Registry saved during login; site discovery or the default can select another target. Set CLAWHUB_REGISTRY in each shell session or pass --registry explicitly.
• Canonical slugs use -- between namespace and skill. SkillHub rejects new namespace or skill slugs containing consecutive --, keeping new coordinates unambiguous. Rename invalid legacy or externally imported coordinates before using the ClawHub CLI.

Quick Start

1. Configure Registry URL

Set the SkillHub registry address for the current shell session:

# Do not depend on the registry resolution order of the login configuration
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

2. Authentication (Optional)

For global namespace (@global) PUBLIC skills, no login is required to download. Authentication is required for:

• Team namespace skills (regardless of visibility)
• NAMESPACE_ONLY or PRIVATE skills
• Authenticated operations such as starring

# Log in with an API token
npx clawhub login --token YOUR_API_TOKEN
# If you have installed clawhub via npm i -g clawhub, you can use clawhub directly instead of npx clawhub for all commands in this document

# View current logged in user
npx clawhub whoami

# Log out current user
npx clawhub logout

# View help
npx clawhub --help

Obtaining an API Token

1. Log in to SkillHub Web UI
2. Navigate to Settings → API Tokens
3. Click Create New Token
4. Set token name and permissions
5. Copy the generated token

3. Search/Explore/View Skills

# Search, display all matching skills
npx clawhub search <skill-name>
# Search, display first 5 results
npx clawhub search <skill-name> --limit 5
# Show skill details
npx clawhub inspect <skill-name>
# Explore latest skills
npx clawhub explore
npx clawhub explore --limit 20    # First 20

# Examples
npx clawhub search find-skills
npx clawhub search find-skills --limit 5
npx clawhub inspect find-skills

# Help
npx clawhub search --help
npx clawhub inspect --help

4. Install/Update/Uninstall Skills

# Install
npx clawhub install <skill-name>
npx clawhub install <skill-name> --version <version number>   # Specific version
npx clawhub install <skill-name> --force                      # Overwrite existing
npx clawhub --dir <install-path> install <skill-name>         # Specific directory

# Update
npx clawhub update <skill-name>
npx clawhub update --all

# Uninstall
npx clawhub uninstall <skill-name>

# View installed skills
npx clawhub list

# Claude Code Installation Skill Example
npx clawhub --dir ~/.claude/skills install find-skills
CLAWHUB_WORKDIR=~/.claude/skills npx clawhub install find-skills

# Help
npx clawhub install --help
npx clawhub update --help
npx clawhub uninstall --help
npx clawhub list --help

5. Publish with the SkillHub CLI

The ClawHub CLI 0.23.3 publishing protocol is not compatible with SkillHub. Use the first-party SkillHub CLI:

export SKILLHUB_REGISTRY=https://skillhub.your-company.com
export SKILLHUB_TOKEN=YOUR_API_TOKEN
npx @astron-team/skillhub@latest publish ./my-skill --namespace global
npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space

Notes:

• Publishing requires an API Token with the skill:publish scope and permission in the target namespace.
• clawhub login and the SkillHub CLI do not share credentials; set SKILLHUB_TOKEN separately for the first-party CLI.
• The first-party CLI uses a separate namespace option, but it still follows the server's slug validation rules.

API Endpoints

SkillHub compatibility layer provides the following endpoints:

Endpoint	Method	Description	Auth Required
/api/v1/whoami	GET	Get current user info	Required
/api/v1/search	GET	Search skills	Optional
/api/v1/resolve	GET	Resolve skill version	Optional
/api/v1/download/{slug}	GET	Download skill (redirect)	Optional*
/api/v1/download	GET	Download skill (query params)	Optional*
/api/v1/skills/{slug}	GET	Get skill details	Optional
/api/v1/stars/{slug}	POST	Star a skill	Required
/api/v1/stars/{slug}	DELETE	Unstar a skill	Required
/api/v1/publish	POST	Legacy compatibility endpoint; not used by ClawHub CLI 0.23.3	Required

Notes:

• The compatibility layer may still expose the term "latest" externally, but it must strictly mean "latest published version"
• Internally, compat responses should map from the unified lifecycle projection's publishedVersion rather than inferring an ad hoc "current version"

* Download endpoint authentication requirements:

• Global namespace (@global) PUBLIC skills: No authentication required
• All team namespace skills: Authentication required
• NAMESPACE_ONLY and PRIVATE skills: Authentication required

Skill Visibility Levels

SkillHub supports three visibility levels with the following download permission rules:

PUBLIC

• ✅ Anyone can search and view
• ✅ Global namespace (@global): No login required to download
• 🔒 Team namespaces: Authentication required to download
• 📍 Suitable for organization-wide, publicly shareable skills

NAMESPACE_ONLY

• ✅ Namespace members can search and view
• 🔒 Login required and must be namespace member to download
• 📍 Suitable for team-internal skills

PRIVATE

• ✅ Only owner can view
• 🔒 Login required and must be owner to download
• 📍 Suitable for skills under personal development

Important Notes:

• Global namespace (@global) PUBLIC skills support anonymous downloads for wide distribution within the organization
• All team namespace skills (including PUBLIC) require authentication to ensure team boundary security

Canonical Slug Mapping

SkillHub internally uses @{namespace}/{skill} format, but the compatibility layer automatically converts to ClawHub-style canonical slugs:

SkillHub Internal	Canonical Slug	Description
@global/my-skill	my-skill	Global namespace skill
@my-team/my-skill	my-team--my-skill	Team namespace skill

OpenClaw CLI uses canonical slug format, and SkillHub handles the conversion automatically.

The canonical format has no escaping rule, so SkillHub rejects new namespace or skill slugs containing consecutive --. If legacy or externally imported data bypassed that validation, rename the coordinate first; the first-party CLI does not bypass server-side slug validation.

Configuration Examples

ClawHub CLI Environment Variables

ClawHub CLI is configured via environment variables:

# Registry configuration
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

# Authenticate once if needed
clawhub login --token sk_your_api_token_here

Environment Variables

# Registry configuration
export CLAWHUB_REGISTRY=https://skillhub.your-company.com

# Optionally log in before running authenticated commands
clawhub login --token sk_your_api_token_here

FAQ

Q: How do I switch back to public ClawHub?

# Unset custom registry
unset CLAWHUB_REGISTRY

# ClawHub CLI will use the default public registry

Q: Getting 403 Forbidden when downloading?

Possible causes:

1. Skill belongs to a team namespace, authentication required
2. Skill is NAMESPACE_ONLY or PRIVATE, authentication required
3. You're not a member of the namespace
4. API Token has expired

Solution:

# Log in again with a new token
clawhub login --token YOUR_NEW_TOKEN

# Test connection
curl https://skillhub.your-company.com/api/v1/whoami \
  -H "Authorization: Bearer YOUR_NEW_TOKEN"

Tip: Global namespace (@global) PUBLIC skills can be downloaded anonymously without authentication.

Q: How do I see all skills I have access to?

# Search all skills (filtered by permissions)
npx clawhub search ""

Q: Why does publishing with the ClawHub CLI fail?

ClawHub CLI 0.23.3 uses an upload-ticket protocol outside SkillHub's compatibility scope. This failure does not mean that the API Token was revoked; use the first-party SkillHub CLI instead.

If the first-party CLI reports insufficient permission:

• The publisher must be a member of the target namespace; SUPER_ADMIN is exempt
• A regular member may submit a publication; visibility and review rules decide whether it is published immediately or enters review
• Contact a namespace administrator to join the target namespace

Q: Which OpenClaw versions are supported?

SkillHub compatibility layer is designed to work with tools using ClawHub CLI. ClawHub CLI is distributed via npm:

# Install ClawHub CLI
npm install -g clawhub

# Or use npx directly
npx clawhub install my-skill

If you encounter compatibility issues, please file an issue.

API Response Formats

Search Response Example

{
  "results": [
    {
      "slug": "my-team--email-sender",
      "name": "Email Sender",
      "description": "Send emails via SMTP",
      "author": {
        "handle": "user123",
        "displayName": "John Doe"
      },
      "version": "1.2.0",
      "downloadCount": 150,
      "starCount": 25,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-10T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Version Resolution Response Example

{
  "slug": "my-skill",
  "version": "1.2.0",
  "downloadUrl": "/api/v1/skills/global/my-skill/versions/1.2.0/download"
}

Publish Response Example

{
  "id": "12345",
  "version": {
    "id": "67890"
  }
}

Security Recommendations

1. Use HTTPS: Always use HTTPS in production
2. Token Management:
   • Rotate API tokens regularly
   • Never hardcode tokens in code
   • Use environment variables or secret management tools
3. Least Privilege: Assign minimum required permissions to tokens
4. Audit Logs: Regularly review SkillHub audit logs

Troubleshooting

Enable Debug Logging

# View detailed request logs
DEBUG=clawhub:* npx clawhub search my-skill

# Or use verbose mode
npx clawhub --verbose install my-skill

Test Connection

# Test registry connection
curl https://skillhub.your-company.com/api/v1/whoami \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test search
curl "https://skillhub.your-company.com/api/v1/search?q=test"

Further Reading

• SkillHub API Design
• Skill Protocol Specification
• Authentication & Authorization
• Deployment Guide

Support

For questions or suggestions:

• 📖 Full Documentation: https://zread.ai/iflytek/skillhub
• 💬 GitHub Discussions: https://github.com/iflytek/skillhub/discussions
• 🐛 Submit Issues: https://github.com/iflytek/skillhub/issues