OpenClaw Plugins Not Loading — Relative Path Fix (2026)

The Relative Path Problem

OpenClaw resolves plugin paths relative to the working directory of the process, not the location of openclaw.json. This is the #1 reason plugins fail to load — especially in Docker containers where the working directory may differ from what you expect.

Step-by-Step Fix

1. Use Absolute Paths

The safest approach is to use absolute paths in your configuration:

{
  "plugins": [
    "/app/plugins/my-custom-plugin.js",
    "/app/plugins/analytics-plugin.js"
  ]
}

2. Fix Docker Volume Mounts

Ensure your plugins directory is mounted into the container:

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    volumes:
      - ./openclaw.json:/app/openclaw.json:ro
      - ./plugins:/app/plugins:ro
      - ./data:/app/data

3. Enable Debug Logging

See exactly what's happening during plugin load:

# Bare metal
OPENCLAW_LOG_LEVEL=debug openclaw start

# Docker
docker run -e OPENCLAW_LOG_LEVEL=debug ghcr.io/openclaw/openclaw:latest

4. Verify Plugin File Permissions

# Ensure the OpenClaw process can read plugin files
chmod 644 plugins/*.js
ls -la plugins/

5. Use npm Packages Instead

For a more reliable approach, install plugins as npm packages:

{
  "plugins": [
    "npm:openclaw-plugin-analytics",
    "npm:openclaw-plugin-rate-limit"
  ]
}

Frequently Asked Questions

Why are my OpenClaw plugins not loading?

The most common cause is incorrect relative paths in your openclaw.json. When running in Docker, paths are relative to the container filesystem, not your host machine. Use absolute paths or ensure volume mounts map correctly.

How do I check which plugins OpenClaw loaded?

Start OpenClaw with debug logging enabled: OPENCLAW_LOG_LEVEL=debug openclaw start. The startup log will list each plugin it attempts to load and any errors encountered.

Can I load plugins from a URL?

Yes, OpenClaw supports loading plugins from URLs and npm packages. Use "plugin": "https://example.com/plugin.js" or "plugin": "npm:openclaw-plugin-name" in your config.

How do I create a custom OpenClaw plugin?

Create a JavaScript/TypeScript file that exports a default function with the OpenClaw plugin interface. See the OpenClaw documentation for the plugin API reference and examples.