How to Fix an OpenClaw Skill That Won’t Load

A skill that won’t load is one of the more frustrating OpenClaw problems because the failure mode is usually silent — the skill just doesn’t respond, or it disappears from the skills list, or it loads but produces no output. The error message, if there is one, rarely points directly at the cause.

This guide covers the 7 most common causes of skill load failures and gives you a decision tree to diagnose which one you’re dealing with in under 5 minutes.

Before You Diagnose: Run the Health Check

@openclaw skill diagnose [skill-name]

This runs through the most common checks automatically:

Diagnosing skill: github-core

✅ Manifest found: ~/.openclaw/skills/github-core/skill.json
✅ Dependencies installed: 7/7
❌ Environment variable missing: GITHUB_APP_PRIVATE_KEY
✅ Port available: N/A (this skill doesn't use a port)
✅ Permissions: directory readable
✅ Version compatible: skill v2.1.0, OpenClaw v1.4.x ✓

Diagnosis: Missing environment variable.
Run: export GITHUB_APP_PRIVATE_KEY="/path/to/private-key.pem"
Then: @openclaw reload skill github-core

If the health check pinpoints the problem, fix it and reload:

@openclaw reload skill [skill-name]

If the health check passes but the skill still doesn’t work, work through the 7 causes below.

The 7 Most Common Causes

Cause 1: Path Problem

The skill loader can’t find the skill files because the path is wrong or the skill isn’t where OpenClaw expects it.

Symptoms:

• Skill doesn’t appear in @openclaw skills list
• Error: “Skill not found” or “No such file or directory”
• Skill was working before you moved or renamed the skills folder

Check:

@openclaw skills path
> Skills directory: /Users/yourname/.openclaw/skills/

ls ~/.openclaw/skills/
> github-core/
> gmail/
> notion-core/

ls ~/.openclaw/skills/github-core/
> skill.json    # Must exist
> index.js      # Or main entry point
> package.json  # If Node.js skill

If the directory exists but skill.json is missing, the skill is corrupted. Reinstall:

@openclaw uninstall skill github-core
@openclaw install skill github-core

If you moved your skills directory:

# ~/.openclaw/config.yaml
skills_directory: "/new/path/to/skills"  # Update this

Then restart OpenClaw.

If you’re on Windows and paths have backslashes:

OpenClaw uses forward slashes in config files even on Windows. C:/Users/yourname/.openclaw/skills not C:Usersyourname.openclawskills.

Cause 2: Permissions Problem

The skill files exist but OpenClaw can’t read or execute them.

Symptoms:

• Skill appears in skills list but shows “Error loading”
• Error message contains “EACCES”, “Permission denied”, or “EPERM”
• Skill works for one user but not another on the same machine

Check:

ls -la ~/.openclaw/skills/github-core/
# Should show rw-r--r-- (644) for files, rwxr-xr-x (755) for directories

Fix permissions:

chmod -R 755 ~/.openclaw/skills/github-core/

Or for all skills:

chmod -R 755 ~/.openclaw/skills/

On Linux: Check if OpenClaw runs as a different user

If OpenClaw runs as a service (systemd), it may run as a different user than your login account. The skill files need to be readable by that user:

# Check which user systemd runs OpenClaw as
systemctl show openclaw --property=User
> User=openclaw-service

# Make files readable by that user
chown -R openclaw-service:openclaw-service ~/.openclaw/skills/

On macOS: Gatekeeper quarantine

Files downloaded from the internet on macOS get a quarantine attribute that can block execution:

xattr -d com.apple.quarantine ~/.openclaw/skills/github-core/index.js
# Or remove quarantine from entire skills directory:
xattr -r -d com.apple.quarantine ~/.openclaw/skills/

Cause 3: Manifest Typo

The skill.json manifest has a syntax error or invalid field. OpenClaw validates the manifest before loading the skill — any error in the JSON causes the skill to fail silently.

Symptoms:

• Skill was working, broke after you manually edited skill.json
• Error: “Invalid manifest” or “JSON parse error”
• New skill you’re building fails to load on first try

Check:

cat ~/.openclaw/skills/github-core/skill.json | python3 -m json.tool
# If valid JSON: prints formatted output
# If invalid: prints error with line number

Or use any JSON validator — paste the content at jsonlint.com.

Common manifest typos:

// ❌ Trailing comma (invalid JSON)
{
  "name": "github-core",
  "version": "2.1.0",
  "main": "index.js",   ← this comma with nothing after it
}

// ✅ Fixed
{
  "name": "github-core",
  "version": "2.1.0",
  "main": "index.js"
}

// ❌ Single quotes (invalid JSON, must use double quotes)
{
  'name': 'github-core'
}

// ✅ Fixed
{
  "name": "github-core"
}

// ❌ Missing required field
{
  "name": "github-core",
  "version": "2.1.0"
  // missing "main" entry point
}

// ✅ Fixed
{
  "name": "github-core",
  "version": "2.1.0",
  "main": "index.js"
}

Required manifest fields:

{
  "name": "skill-name",           // Required: matches directory name
  "version": "1.0.0",             // Required: semver
  "main": "index.js",             // Required: entry point file
  "openclaw_version": ">=1.3.0",  // Required: compatibility range
  "description": "...",           // Recommended
  "permissions": []               // Required if skill needs permissions
}

Cause 4: Missing Dependency

The skill requires a package that isn’t installed.

Symptoms:

• Error: “Cannot find module ‘some-package’”
• Error: “ModuleNotFoundError: No module named ‘requests’”
• Skill installed fine but fails when you actually use it
• Skill works on one machine but not another

Check for Node.js skills:

cd ~/.openclaw/skills/github-core/
cat package.json  # Look at "dependencies"
ls node_modules/  # Check if they're installed

Fix:

cd ~/.openclaw/skills/github-core/
npm install

Or reinstall the skill entirely (this runs dependency installation automatically):

@openclaw reinstall skill github-core

Check for Python skills:

cd ~/.openclaw/skills/your-python-skill/
cat requirements.txt
pip list | grep -f requirements.txt  # Check what's installed vs required

Fix:

pip install -r requirements.txt --break-system-packages

The “works on my machine” scenario:

If a skill works on one computer but not another, the missing machine probably has a different Node or Python version that doesn’t auto-install global dependencies. Always run npm install or pip install -r requirements.txt after copying a skill to a new machine.

Cause 5: Version Mismatch

The skill requires a newer (or older) version of OpenClaw than you’re running, or requires a Node/Python version you don’t have.

Symptoms:

• Error: “Incompatible OpenClaw version”
• Error: “This skill requires OpenClaw >= 1.5.0”
• Skill loaded in the past but broke after an OpenClaw update
• API calls work but skill-specific features fail silently

Check:

@openclaw version
> OpenClaw v1.4.2

@openclaw skill info github-core
> github-core v2.1.0
> Requires: OpenClaw >=1.5.0  ← incompatible

Fix Option A: Update OpenClaw

npm update -g openclaw
# or
npm install -g openclaw@latest

Fix Option B: Use an older skill version

@openclaw install skill [email protected]  # Specific older version

Fix Option C: Check Node.js version

Some skills use newer JavaScript features that require Node 18+:

node --version
> v16.14.0  ← too old for some skills

# Update Node via nvm:
nvm install 20
nvm use 20

After an OpenClaw update that broke skills:

@openclaw skills check-compatibility
> github-core v2.1.0 — ✅ compatible
> old-skill v0.9.1 — ❌ deprecated API used, update needed
> custom-skill v1.0.0 — ✅ compatible

Cause 6: Port Collision

Skills that run as local servers (usually skills with web interfaces or that receive webhooks) need to bind to a port. If that port is already in use, the skill fails to start.

Symptoms:

• Error: “EADDRINUSE: address already in use :::3847”
• Error: “Port 3847 is already in use”
• Skill starts loading then immediately stops
• Two skills that used to work together now conflict

Check which process is using the port:

# macOS/Linux
lsof -i :3847
# or
ss -tulpn | grep 3847

# Windows
netstat -ano | findstr :3847

Fix Option A: Change the skill’s port

# skill-specific config (location varies by skill)
server_port: 3848  # Change from default 3847

Fix Option B: Kill the conflicting process

# If it's another OpenClaw skill or a leftover process:
kill -9 [PID from lsof output]

Fix Option C: Let OpenClaw auto-assign ports

# ~/.openclaw/config.yaml
skill_port_range:
  start: 3800
  end: 3900
  auto_assign: true  # Skills pick available ports automatically

With auto-assign enabled, port conflicts resolve themselves on restart.

Common default ports used by skills:

Cause 7: Missing or Wrong Environment Variable

The skill requires an environment variable (API key, file path, URL) that isn’t set, is set to the wrong value, or isn’t visible to the process running OpenClaw.

This is the most common cause overall and the one most likely to produce a confusing error message (or no error message at all — the skill loads but quietly fails on first use).

Symptoms:

• Skill loads but returns “Authentication failed” or “API key invalid”
• Skill health check passes but first command fails
• Error: “Cannot read property of undefined” (often means an env var is undefined and code tries to use it)
• Works in terminal but not as a background service

Check what the skill needs:

@openclaw skill info github-core
> Required environment variables:
>   GITHUB_APP_ID — Your GitHub App ID
>   GITHUB_APP_PRIVATE_KEY — Path to .pem private key file
>   GITHUB_INSTALLATION_ID — Installation ID
>
> Current status:
>   GITHUB_APP_ID: ✅ set
>   GITHUB_APP_PRIVATE_KEY: ❌ not set
>   GITHUB_INSTALLATION_ID: ✅ set

Fix Option A: Set in terminal session

export GITHUB_APP_PRIVATE_KEY="/Users/yourname/.openclaw/keys/github-app.pem"

This only persists for the current terminal session. If you restart the terminal or OpenClaw, it’s gone.

Fix Option B: Add to shell profile (persists across sessions)

# Add to ~/.zshrc or ~/.bashrc
echo 'export GITHUB_APP_PRIVATE_KEY="/Users/yourname/.openclaw/keys/github-app.pem"' >> ~/.zshrc
source ~/.zshrc

Fix Option C: Add to OpenClaw’s env file (recommended)

# ~/.openclaw/.env
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY=/Users/yourname/.openclaw/keys/github-app.pem
GITHUB_INSTALLATION_ID=78901234
NOTION_TOKEN=secret_xxxx
GMAIL_CREDENTIALS_PATH=/Users/yourname/.openclaw/gmail-credentials.json

OpenClaw loads this file automatically on startup. Variables set here are available to all skills without needing to set them in every terminal session.

The “works in terminal, not in service” problem:

When OpenClaw runs as a systemd service or background process, it doesn’t inherit your shell’s environment variables. The .env file approach above solves this. Alternatively:

# For systemd service, add env vars to the service file
sudo systemctl edit openclaw
# Add:
[Service]
Environment="GITHUB_APP_PRIVATE_KEY=/path/to/key.pem"

The Decision Tree

Use this to narrow down the cause in under 5 minutes:

Skill won't load or isn't working
│
├─ Does "@openclaw skills list" show the skill?
│   ├─ NO → Cause 1 (Path) or Cause 3 (Manifest)
│   │   └─ Run: ls ~/.openclaw/skills/[skill-name]/skill.json
│   │       ├─ File missing → Path problem (Cause 1)
│   │       └─ File exists → Validate skill.json (Cause 3)
│   │
│   └─ YES → Continue ↓
│
├─ Does the skill show "Error loading" next to it?
│   └─ YES → Run: @openclaw skill diagnose [skill-name]
│       ├─ Permission error → Cause 2
│       ├─ Port in use → Cause 6
│       └─ Version error → Cause 5
│
├─ Skill loads but fails when you use it?
│   ├─ "Authentication failed" / "API key" → Cause 7 (Env var)
│   ├─ "Cannot find module" / "ModuleNotFound" → Cause 4 (Dependency)
│   └─ Worked before an update → Cause 5 (Version)
│
└─ Skill works in terminal but not as a service?
    └─ Cause 7 (Env var not available to service process)

Quick-Fix Command Reference

# Run full diagnosis
@openclaw skill diagnose [skill-name]

# Check all skills at once
@openclaw skills status

# Reload a skill without restarting OpenClaw
@openclaw reload skill [skill-name]

# Full reinstall (fixes most install issues)
@openclaw reinstall skill [skill-name]

# Check skill version compatibility
@openclaw skills check-compatibility

# View skill error logs
@openclaw skill logs [skill-name] --lines 50

# Check which ports skills are using
@openclaw skills ports

When to Reinstall vs. Debug

Reinstall when:

• The skill came from the marketplace and was working before
• You’re not sure what changed
• Quick debugging isn’t revealing anything

@openclaw reinstall skill [skill-name]

A reinstall re-downloads the skill, installs dependencies, and reconfigures from your saved credentials. It preserves your credential configuration and skill settings.

Debug when:

• You built the skill yourself
• You made manual changes to skill files
• The error message gives you a specific file or line number
• Reinstalling doesn’t fix it

File a bug when:

• The skill installs cleanly but fails consistently on first use
• The error is cryptic with no clear cause after working through all 7 causes
• Multiple users report the same issue

@openclaw skill report-issue [skill-name]

This collects diagnostic information (sanitized — no API keys) and opens a pre-filled GitHub issue template.

Summary

The 7 causes in order of how often they occur in practice: missing environment variable (most common), missing dependency, version mismatch, manifest typo, path problem, permissions, port collision. The health check command catches most of these automatically. When it doesn’t, the decision tree above narrows it down to the right section within a few questions.

The .env file at ~/.openclaw/.env is the single most useful habit to develop — putting all credentials there means they’re available to all skills regardless of how OpenClaw is started, and you never deal with the “works in terminal, not in service” problem again.