Skills Issues

This page helps you fix problems specific to OpenClaw skills-plugins from the ClawHub marketplace that add tools and capabilities to your agent. Issues covered here include skill installation failures, skills that won't load, credential leaks in skills, malicious skill detection, and version conflicts. For general gateway or channel errors, use the Troubleshooting Guide and Quick diagnostics.

🔧 Start with diagnostics. Run openclaw doctor first to check gateway health and config. For skill-related security (credential leaks, malware), run openclaw security audit and see Skills Security Audit and OpenClaw Skills Security.

Quick Diagnostic

Use these commands when troubleshooting skills:

# Full health check (do this first)
openclaw doctor

# Optional: apply safe fixes (dev/test only)
openclaw doctor --fix

# Check gateway and service status
openclaw status
openclaw status --all

# Scan installed skills for security issues (credential leaks, policy violations)
openclaw security audit

# View recent logs (look for skill load errors)
openclaw logs --tail 50
openclaw logs --follow

# Validate configuration (skills config, paths)
openclaw config validate

Skill list: Use openclaw skills list to see installed skills and versions. If a skill is missing from the list after install, see Skill won't load below.

Common Skills Issues & Solutions

Jump to the section that matches your problem:

Symptom Likely Cause Solution
Skill installation failed Network, wrong package name, permissions, disk space, ClawHub unreachable See below - check npm/network, openclaw skills install syntax, retry
Skill won't load Config missing/invalid, dependency error, gateway version mismatch, runtime error See below - validate config, check logs, ensure gateway and skill versions match
Credential leak in skill Skill logs or sends secrets; Snyk found ~7.1% of ClawHub skills could leak credentials Run openclaw security audit, remove or update skill; see Skills Security Audit
Malicious or suspicious skill Fake crypto tools, malware, unexpected network/file access reported in marketplace Disable and uninstall skill, rotate exposed credentials; see Malicious skill detection
Version conflicts Skill and gateway version mismatch; dependency conflicts after update See below - pin versions, update gateway or skill, resolve dependencies

Skill Installation Failed

If openclaw skills install <skill-name> fails, common causes and fixes:

  • Wrong or typo in package name - Search ClawHub or run openclaw skills search <keyword> to get the exact package name. Use the name shown in the ClawHub Marketplace.
  • Network or registry unreachable - Check internet connectivity, proxy, and firewall. If you're behind a corporate firewall, ensure npm/registry access is allowed. Try npm ping or install a known-good skill to isolate.
  • Permissions - The OpenClaw data directory (e.g. ~/.openclaw) must be writable. On Linux/macOS, check ownership and chmod if needed. On Windows, run as a user with write access to the install path.
  • Disk space - Ensure enough free space for the skill and its dependencies. Clear old logs or temporary files if low.
  • Node/npm version - OpenClaw requires Node.js 22+. Run node -v and upgrade if necessary. See Installation errors for Node/PATH issues.
  • ClawHub or registry down - Check status pages or community (Discord, GitHub). Retry later or install from source if the skill provides a Git URL.

After fixing, run openclaw skills install <skill-name> again. For full install/update workflow, see Installing Skills.

Skill Won't Load

Installed skill doesn't appear or the agent can't use it:

  • Config missing or invalid - Skills often need an entry in your OpenClaw config (e.g. under skills or channel/agent config). Check the skill's README or ClawHub page for required config. Run openclaw config validate to catch schema errors. See Configuration File Guide and Configuration problems.
  • Dependency or runtime error - Check openclaw logs --tail 100 for stack traces or "failed to load skill" messages. A missing system library or Node module can prevent load. Install any OS-level dependencies the skill documents.
  • Gateway version mismatch - Some skills require a minimum (or maximum) OpenClaw gateway version. Upgrade OpenClaw with npm update -g openclaw (or your install method) and restart the gateway. See Gateway issues if the gateway itself won't start.
  • Skill disabled or not enabled for channel - Verify the skill is enabled in config and, if applicable, enabled for the channel or agent you're using.

Use openclaw skills list to confirm the skill is installed. If it lists but the agent doesn't use it, the issue is usually config or channel/agent assignment.

Credential Leaks in Skills

Security researchers (e.g. Snyk) have reported that a notable portion of ClawHub skills could leak credentials-for example by logging secrets, embedding them in error messages, or sending them to external endpoints. To detect and fix:

  • Run openclaw security audit - Scans installed skills and config for known issues and credential exposure. Run after every new skill install and periodically. Fix or remove any skill that fails the audit.
  • Store secrets in environment variables or a secrets manager - Not in config files that skills might read. See Credential Management.
  • Limit which credentials skills can access - Only pass the minimum required; avoid broad API keys or root access. See Skills Security Audit and OpenClaw Skills Security.

Malicious Skill Detection

There have been reports of malware and fake crypto tools in the ClawHub marketplace. Red flags and what to do:

  • Unexpected network calls - Skill contacts unknown IPs/domains or sends sensitive data out. Use audit logging and monitoring to spot this.
  • Broad or suspicious file access - Reading/writing config files, SSH keys, or credential stores without a clear need.
  • Fake or misleading descriptions - Promises of "free crypto" or "guaranteed returns" often accompany scam skills.
  • Obfuscated code or no visible source - Prefer skills with visible source (e.g. GitHub) so you or the community can review.

If you suspect a skill: Disable it immediately in config, uninstall it (openclaw skills uninstall <skill-name> or equivalent), rotate any exposed API keys or secrets, and check Known Vulnerabilities and official advisories. Run openclaw security audit and see Skills Security Audit for a full checklist.

Version Conflicts

Skills and the OpenClaw gateway depend on specific versions. Conflicts can cause install failures or "skill won't load" errors.

  • Pin skill versions - Install a specific version, e.g. openclaw skills install skill-name@1.2.0, so updates don't pull in broken or malicious changes. See Installing Skills for syntax.
  • Upgrade gateway or skill - If the skill requires a newer gateway, upgrade OpenClaw. If the gateway was upgraded and the skill broke, check the skill's changelog for compatibility; pin an older skill version if needed.
  • Dependency conflicts - Multiple skills may pull in conflicting versions of the same dependency. Isolate by disabling other skills temporarily, or report the conflict to the skill author and OpenClaw community. Check logs for npm/Node dependency errors.

Related Troubleshooting & Guides

Getting Help

If you're still stuck:

When reporting, include: skill name and version, OpenClaw version, OS, and the exact error message or log snippet.