Skills config

Most skills loader/install configuration lives under

in . Agent-specific skill visibility lives under and .

json5
Copy
{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

For built-in image generation/editing, prefer

plus the core tool. is only for custom or third-party skill workflows.

If you select a specific image provider/model, also configure that provider's auth/API key. Typical examples:

or for , for , and for .

Examples:

• Native Nano Banana Pro-style setup:
  text

  Copy

  agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"
• Native fal setup:
  text

  Copy

  agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

Agent skill allowlists

Use agent config when you want the same machine/workspace skill roots, but a different visible skill set per agent.

json5
Copy
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits defaults -> github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

Rules:

• text

  Copy

  agents.defaults.skills
  : shared baseline allowlist for agents that omit
  text

  Copy

  agents.list[].skills
  .
• Omit
  text

  Copy

  agents.defaults.skills
  to leave skills unrestricted by default.
• text

  Copy

  agents.list[].skills
  : explicit final skill set for that agent; it does not merge with defaults.
• text

  Copy

  agents.list[].skills: []
  : expose no skills for that agent.

Fields

• Built-in skill roots always include
  text

  Copy

  ~/.openclaw/skills
  ,
  text

  Copy

  ~/.agents/skills
  ,
  text

  Copy

  <workspace>/.agents/skills
  , and
  text

  Copy

  <workspace>/skills
  .
• text

  Copy

  allowBundled
  : optional allowlist for bundled skills only. When set, only bundled skills in the list are eligible (managed, agent, and workspace skills unaffected).
• text

  Copy

  load.extraDirs
  : additional skill directories to scan (lowest precedence).
• text

  Copy

  load.watch
  : watch skill folders and refresh the skills snapshot (default: true).
• text

  Copy

  load.watchDebounceMs
  : debounce for skill watcher events in milliseconds (default: 250).
• text

  Copy

  install.preferBrew
  : prefer brew installers when available (default: true).
• text

  Copy

  install.nodeManager
  : node installer preference (
  text

  Copy

  npm
  |
  text

  Copy

  pnpm
  |
  text

  Copy

  yarn
  |
  text

  Copy

  bun
  , default: npm). This only affects skill installs; the Gateway runtime should still be Node (Bun not recommended for WhatsApp/Telegram).
  • text

    Copy

    openclaw setup --node-manager
    is narrower and currently accepts
    text

    Copy

    npm
    ,
    text

    Copy

    pnpm
    , or
    text

    Copy

    bun
    . Set
    text

    Copy

    skills.install.nodeManager: "yarn"
    manually if you want Yarn-backed skill installs.
• text

  Copy

  entries.<skillKey>
  : per-skill overrides.
• text

  Copy

  agents.defaults.skills
  : optional default skill allowlist inherited by agents that omit
  text

  Copy

  agents.list[].skills
  .
• text

  Copy

  agents.list[].skills
  : optional per-agent final skill allowlist; explicit lists replace inherited defaults instead of merging.

Per-skill fields:

• text

  Copy

  enabled
  : set
  text

  Copy

  false
  to disable a skill even if it’s bundled/installed.
• text

  Copy

  env
  : environment variables injected for the agent run (only if not already set).
• text

  Copy

  apiKey
  : optional convenience for skills that declare a primary env var. Supports plaintext string or SecretRef object (
  text

  Copy

  { source, provider, id }
  ).

Notes

• Keys under
  text

  Copy

  entries
  map to the skill name by default. If a skill defines
  text

  Copy

  metadata.openclaw.skillKey
  , use that key instead.
• Load precedence is
  text

  Copy

  <workspace>/skills
  →
  text

  Copy

  <workspace>/.agents/skills
  →
  text

  Copy

  ~/.agents/skills
  →
  text

  Copy

  ~/.openclaw/skills
  → bundled skills →
  text

  Copy

  skills.load.extraDirs
  .
• Changes to skills are picked up on the next agent turn when the watcher is enabled.

Sandboxed skills + env vars

When a session is sandboxed, skill processes run inside the configured sandbox backend. The sandbox does not inherit the host

.

Use one of:

• text

  Copy

  agents.defaults.sandbox.docker.env
  for the Docker backend (or per-agent
  text

  Copy

  agents.list[].sandbox.docker.env
  )
• bake the env into your custom sandbox image or remote sandbox environment

Global

and apply to host runs only.

Related

• Skills
• Creating skills
• Slash commands