OpenClaw skills configuration

Most of what decides which skills an OpenClaw agent sees and how they are installed lives under one key in the config file, with per-agent visibility under the agent entries. The reference page is long because the schema covers loading, installing, gating, the Workshop and a host-owned install policy. Here is the whole surface in order: loading and symlinks, install preferences, the install policy and how it fails closed, the bundled allowlist and per-skill entries, agent allowlists and what they are not, the Workshop settings, and the sandbox trap.

Loading and installing

• Extra directories are scanned at the lowest precedence, below bundled and plugin skills, with tilde expansion; trusted symlink targets are the real directories a symlinked skill folder may resolve into even when the link lives outside the configured root, and the docs say to keep that list narrow rather than pointing it at a home directory; the watcher, on by default, refreshes the skills snapshot when a skill file changes.
• Install preferences: prefer Homebrew installers when available, a Node package manager among npm, pnpm, yarn and bun that affects only skill installs, and an off-by-default switch that lets trusted admin clients install private zip archives staged through the upload flow.
• The operator install policy runs a trusted local command after OpenClaw has staged the source and before an install or update continues, for ClawHub, uploaded, Git and local skills, dependency installers and plugin sources; it receives one JSON object describing the target, source and origin and answers allow, warn or block with a reason and optional findings. Enabled without a valid command, installs fail closed, and so do a block, a non-zero exit, a timeout, invalid JSON or a missing reason.
• A warning stops the install before commit: interactive commands ask the operator to type the target name and re-run the policy, non-interactive commands can pass an explicit acknowledgement flag, the Control UI can review plugin-install warnings, other Gateway-backed and automatic installs stay blocked, and force never approves a warning. Findings are capped at one hundred, the rendered notice at four thousand characters, the deep doctor run executes a synthetic install probe, and bulk updates apply the policy per target.

Agent skill allowlists are a visibility and loading filter for OpenClaw skill discovery, prompts, slash-command discovery, sandbox sync, and skill snapshots. They are not a shell-time authorization boundary.

Entries and allowlists

The bundled allowlist restricts only bundled skills; managed, agent-level and workspace skills are unaffected. Per-skill entries are keyed by the skill name, or by its declared skill key: an enabled flag that disables a skill even when bundled or installed, and that is what switches on the opt-in coding-agent skill once a supported CLI is installed and logged in; an API-key convenience field for skills that declare a primary environment variable, as plain text or a secret reference; environment variables injected for the agent run only when not already set in the process; and a free bag for custom fields. Built-in image generation uses the media model settings and the core image tool rather than an entry. Agent allowlists give the same machine and workspace roots a different visible set per agent: a shared baseline under the defaults, inherited by agents that omit their own list, and explicit lists that replace the defaults entirely, with an empty list exposing no skills. The warning matters: if an agent can run host exec, that shell can still run external clients and read host files visible to the execution user, including MCP client registries, so per-agent isolation needs sandbox or OS-user isolation, a denied or tight exec allowlist, and per-agent credentials at the MCP server.

Workshop, symlinks, sandboxes

• Workshop settings: an autonomous mode of off, propose or auto, where auto, the default, uses normal agent tools for direct per-turn and weekly maintenance without proposal scanning while propose creates pending proposals from corrections and substantial completed work; an approval policy of auto or pending; a maximum of fifty pending and quarantined proposals per agent within a range of one to two hundred; and a maximum proposal body of forty thousand bytes within a range of roughly one thousand to two hundred thousand, with descriptions hard-capped at 160 bytes.
• Workspace, project-agent, extra-dir and bundled skill roots are containment boundaries, so a symlinked skill folder that resolves outside its root is skipped with a log line unless its target is trusted; managed and personal skill directories accept skill-directory symlinks unconditionally, and the Workshop uses each agent’s own containment directory, ignores the trusted-target list and rejects symlinks that escape it.
• Per-skill env and API-key values apply to host runs only: inside a sandbox they have no effect, so a skill that depends on a key fails with a not-configured error unless the sandbox is given the variable separately through the Docker sandbox env, and users with Docker daemon access can read those values through container metadata, so a mounted secret file or a custom image is the answer when that exposure is unacceptable.

OpenClaw self-learning explains the eligibility and privacy rules behind the autonomous mode, and Create an OpenClaw skill the file the loader is watching for.

Why the boundary note matters

The schema mixes visibility controls with security controls, and the docs are careful to say which is which: allowlists shape what the agent is offered, the install policy shapes what can be installed, and only sandboxing or OS-user separation shapes what a shell can reach. OpenClaw sandboxing explained is that last layer, and OpenClaw plugins the sibling install surface the policy also covers.

On Diali

On Diali the skills hub in the dashboard is the front for this file: switching a skill on and pasting its key is what becomes the entry on the assistant, and there is no host shell to edit it by hand. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary around each one.

• Allowlists replace; they never merge.
• The install policy fails closed on anything but a clean allow.
• Skill env vars stop at the sandbox wall.