Configure OpenClaw Skills: Custom Settings Guide

Ever felt like your AI agent has too many tools, or maybe not enough? Managing how your agent interacts with your system requires a solid OpenClaw skills configuration to keep things running exactly how you want.

Most of your setup for loading and installing skills lives right inside the skills section of your ~/.openclaw/openclaw.json file. This is where you tell the system where to look for code and how to handle dependencies. You can also control agent-specific skill visibility under agents.defaults.skills and agents.list[].skills to keep your workspace organized.

{
  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 },
    },
  },
}

If you want to use built-in image generation or editing, you should probably use agents.defaults.imageGenerationModel along with the core image_generate tool. The skills.entries.* section is really meant for your custom or third-party skill workflows.

When you pick a specific image provider or model, you also need to set up that provider’s authentication or API key. You will usually see examples like GEMINI_API_KEY or GOOGLE_API_KEY for google/* models, OPENAI_API_KEY for openai/*, and FAL_KEY for fal/*.

Here are a couple of ways you might set that up:

1. Native Nano Banana-style setup: agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"
2. Native fal setup: agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

Manage Agent Skill Allowlists

You can use agent-specific configurations when you want the same machine or workspace to have different visible skill sets for different agents. This is perfect for limiting what a specific bot can do without changing your global settings for every single agent you run.

{
  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
    ],
  },
}

When you are setting these up, keep these rules in mind:

1. agents.defaults.skills acts as a shared baseline allowlist for any agents that do not have their own agents.list[].skills defined.
2. If you omit agents.defaults.skills, your skills will remain unrestricted by default.
3. agents.list[].skills provides the explicit final skill set for that specific agent, and it does not merge with your defaults.
4. Setting agents.list[].skills: [] ensures that no skills are exposed for that specific agent.

Available Configuration Fields

There are several specific fields available to help you fine-tune how OpenClaw handles everything from installation to folder watching. These settings ensure your development workflow stays fast and predictable while managing your CLI tools.

1. Built-in skill roots always include ~/.openclaw/skills, ~/.agents/skills, <workspace>/.agents/skills, and <workspace>/skills.
2. allowBundled is an optional allowlist specifically for bundled skills. When you set this, only the bundled skills in the list are eligible for use.
3. load.extraDirs lets you define additional skill directories to scan, though these have the lowest precedence.
4. load.watch tells the system to watch skill folders and refresh the skills snapshot, which is set to true by default.
5. load.watchDebounceMs sets the debounce time for skill watcher events in milliseconds, defaulting to 250.
6. install.preferBrew tells the system to prefer brew installers when they are available.
7. install.nodeManager sets your node installer preference, such as npm, pnpm, yarn, or bun.
8. The Gateway runtime should still be Node.js even if you use other managers for skills, as bun is not recommended for platforms like WhatsApp or Telegram.
9. The command openclaw setup --node-manager is a bit narrower and currently accepts npm, pnpm, or bun. You should set skills.install.nodeManager: "yarn" manually if you want Yarn-backed installs.
10. entries.<skillKey> allows for per-skill overrides.
11. agents.defaults.skills is an optional default skill allowlist inherited by agents.
12. agents.list[].skills is the optional per-agent final skill allowlist that replaces inherited defaults.

For individual skills, you can use these fields:

1. enabled: Set this to false to disable a skill even if it is bundled or installed.
2. env: These are environment variables injected for the agent run, but only if they are not already set.
3. apiKey: This is a convenience option for skills that need a primary environment variable, supporting either a plaintext string or a SecretRef JSON object.

Important Notes and Precedence

Understanding the order in which skills are loaded will save you a lot of time when you are debugging your setup. Changes are usually picked up automatically on the next agent turn if you have the watcher active in your configuration.

1. Keys under entries map to the skill name by default. If a skill defines metadata.openclaw.skillKey, you should use that key instead.
2. The load precedence follows this order: <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled skills → skills.load.extraDirs.
3. When the watcher is enabled, any changes you make to your skills are picked up the next time the agent takes a turn.

Sandboxed skills and environment variables

When your session is sandboxed, the skill processes run inside a controlled environment like Docker. Because of this, the sandbox won’t automatically see the environment variables on your host machine’s process.env.

To handle this, you should use one of these methods:

1. Use agents.defaults.sandbox.docker.env for the Docker backend, or set it per-agent using agents.list[].sandbox.docker.env.
2. Bake the environment variables directly into your custom sandbox image or your remote sandbox environment.
3. Remember that global env and skills.entries.<skill>.env/apiKey settings only apply to runs happening on your host machine.

AI Setup Assistant

Next Steps

1. OpenClaw CLI Reference
2. Creating Custom Skills
3. Docker Sandbox Setup