How to Use OpenClaw Skills Config

Skills config decides which AgentSkills OpenClaw can see, install, enable, and expose to each agent. That is different from writing a skill. The config layer controls roots, bundled allowlists, installer preferences, per-skill environment, API keys, and per-agent visibility. If you run more than one agent or use third-party skills, this config becomes part of your security model as much as your convenience model.

30-second answer

Use the skills block in ~/.openclaw/openclaw.json for loader and install behavior. Use agents.defaults.skills and agents.list[].skills when you need different visible skill sets per agent. Built-in skill roots include ~/.openclaw/skills, ~/.agents/skills, workspace .agents/skills, and workspace skills. load.extraDirs adds more directories at lower precedence, and entries. controls specific skills.

Where it fits

Use skills config when you want to install a shared skill pack, disable a bundled skill, inject a provider API key, or keep one agent locked down while another has broader tools. For example, a public support bot might expose only knowledge-base skills, while a private operator agent can see GitHub, weather, and deployment helpers. Skill visibility should match the agent’s job.

Docs-grounded facts

• Skills loader and install config lives under skills.
• Agent-specific visibility lives under agents.defaults.skills and agents.list[].skills.
• agents.list[].skills replaces defaults instead of merging.
• Built-in roots include workspace skills and user skill directories.
• entries.<skillKey>.enabled can disable a skill.
• Sandboxed skill processes do not inherit host process.env.

Set it up deliberately

The docs show skills.allowBundled for bundled skill allowlisting, skills.load.extraDirs for additional roots, watch and watchDebounceMs for refresh behavior, install.preferBrew and install.nodeManager for installer preferences, and entries for per-skill enabled, env, and apiKey values. The apiKey field can be plaintext or a SecretRef object. Use the skill metadata key when a skill declares metadata.openclaw.skillKey.

Use it safely

Do not use skills.entries.* for built-in image generation when the core image_generate tool and agents.defaults.imageGenerationModel are the right path. Do not assume sandboxed skills can see host env vars. The docs are clear: sandboxed sessions need sandbox env configuration, baked images, or remote sandbox environment setup. Host-only env injection does not cross the sandbox boundary.

Common mistakes

The common mistake is expecting agents.list[].skills to merge with defaults. It does not. An explicit per-agent list replaces inherited defaults. Another mistake is leaving skills unrestricted on a multi-agent machine, then being surprised when a narrow agent sees broad tools. Omit defaults only when unrestricted visibility is truly intended.

Verification checklist

After changing skills config, start a new agent turn and inspect available skills or tools. Confirm disabled skills are absent, enabled skills have their env, and sandboxed runs can access only what the sandbox received. For third-party skills, test one harmless command before trusting the workflow.

Playbook angle

The OpenClaw Playbook treats skills config like role design. Give each agent the smallest useful skill set, document why it exists, and avoid mixing personal operator tools into public or team-facing agents.

Operator note

How to Use OpenClaw Skills Config works best when it is written into a small runbook instead of left as tribal knowledge. Record the intended owner, the exact config surface, the channel where results should appear, the allowed inputs, the expected output, and the rollback step. OpenClaw gives agents broad tools, but the durable value comes from making each tool boring, repeatable, and auditable. I would rather have one well-scoped skills config workflow that survives a restart than five clever demos nobody can safely run next week. If the runbook cannot explain when not to use it, keep refining before automation becomes default.