openclaw-skills-how-they-are-stored.md

/home/ubuntu/.openclaw/workspace/docs/openclaw-skills-how-they-are-stored.md

Back

OpenClaw skills: what’s “installed” vs what’s “configured”

This doc explains where OpenClaw stores:

the list of skills available/installed on a machine
the per-skill configuration (API keys, tokens, etc.)
why openclaw.json often shows only a few skills

Key idea

OpenClaw separates:

Skills (code) → stored on disk as directories (installed packages)
Skill configuration (secrets/settings) → stored in the Gateway config file (openclaw.json)

So it’s normal for the “installed skills list” and the “configured skills list” to look different.

1) Where the per-skill config is stored (API keys, etc.)

When you add a skill key through the OpenClaw UI, it’s written to the Gateway config file.

Config path:
- /home/ubuntu/.openclaw/openclaw.json
Example location inside config:
- skills.entries.notion.apiKey

At runtime, OpenClaw reads this config and typically injects the secret into the agent process environment, e.g.:

NOTION_API_KEY

“UI key” vs “file-based key”

Some skill docs show a file-based pattern (useful for manual CLI work), e.g. Notion:

~/.config/notion/api_key

That file is optional if OpenClaw is already providing NOTION_API_KEY from its config.

2) Where the installed/available skills live (the real “skills list”)

OpenClaw does not keep a single authoritative “installed skills list” in openclaw.json.

Instead, the available skills are discovered from directories on disk.

A) Built-in / globally installed skills (most common)

On this host, the main set of skills is installed with the global OpenClaw package:

Directory:
- /home/ubuntu/.npm-global/lib/node_modules/openclaw/skills/

Each subdirectory corresponds to one skill (e.g. notion/, gog/, github/, etc.).

B) User-installed / custom skills (optional)

OpenClaw also supports skills installed/linked in the user area:

Directory:
- /home/ubuntu/.openclaw/skills/

On this machine, that folder exists but currently only contains a symlink (find-skills) and no additional custom skills.

3) Why `openclaw.json` may show only one skill (e.g. Notion)

Because:

openclaw.json is a configuration file, not an inventory.
skills.entries only includes skills that have explicit saved configuration (API keys/settings).

So it’s normal to see only something like:

"skills": {
  "entries": {
    "notion": { "apiKey": "…" }
  }
}

Even if dozens of skills are installed and available.

4) Practical “mental model”

If you want to know what skills exist on the machine → look at the skills directories on disk.
If you want to know which skills are configured (have keys/settings saved via UI) → look in:
- /home/ubuntu/.openclaw/openclaw.json under skills.entries.
If a skill “works in the UI” but a standalone script fails, it’s often because the script expects a key in a local file (like ~/.config/notion/api_key) while OpenClaw is providing it via env var.

5) Notes / safety

Any time a config file containing secrets is printed/logged, assume it may be exposed to logs.
Best practice is to avoid dumping full config contents; prefer redaction.
If a secret was exposed, rotate it in the provider (e.g., Notion integration) and re-enter it in the UI.