Principle:Openclaw Openclaw Extension Configuration

Extension Configuration

Extension Configuration is the principle governing how OpenClaw extensions (both plugins and skills) are enabled, disabled, configured with per-extension settings, and managed through allow/deny lists. Configuration drives the runtime behavior of the extension system, determining which extensions are active and how they behave.

Overview

OpenClaw's extension system separates installation from configuration. A plugin can be installed on disk but disabled in configuration. A skill can exist in a skills directory but be excluded by eligibility criteria or an explicit disable flag. Configuration is the mechanism that bridges the gap between available extensions and active extensions.

Plugin Configuration Model

Plugin configuration operates at two levels:

Global Level

Setting	Type	Effect
plugins.enabled	boolean	Master switch. When false, no plugins are loaded regardless of per-plugin settings.
plugins.allow	string[]	When present, only plugins whose ID is in this list can be loaded.
plugins.deny	string[]	Plugins whose ID is in this list are unconditionally blocked. Takes precedence over the allow list.
plugins.slots.memory	string	Designates which memory-kind plugin should be active. Set to "none" to disable all memory plugins.
plugins.load.paths	string[]	Additional filesystem paths to scan for plugin directories.

Per-Plugin Level

Each plugin can have an entry in plugins.entries.<pluginId>:

Setting	Type	Effect
enabled	boolean	Explicitly enable or disable this specific plugin.
config	Record<string, unknown>	Arbitrary configuration values validated against the plugin's config schema.

Skill Configuration Model

Skill configuration also operates at two levels:

Global Level

Setting	Type	Effect
skills.allowBundled	string[]	When present, only bundled skills in this list are loaded. Non-bundled skills are unaffected.
skills.load.extraDirs	string[]	Additional directories to scan for skills.
skills.load.watch	boolean	Whether to watch skill directories for changes.
skills.install.preferBrew	boolean	Prefer Homebrew for installing skill dependencies.
skills.install.nodeManager	string	Preferred Node package manager for skill dependency installation.

Per-Skill Level

Each skill can have an entry in skills.entries.<skillKey>:

Setting	Type	Effect
enabled	boolean	Explicitly enable or disable this specific skill.
apiKey	string	API key that satisfies the skill's primaryEnv requirement.
env	Record<string, string>	Environment variable overrides for eligibility checking.
config	Record<string, unknown>	Arbitrary configuration values for the skill.

Enable/Disable Logic

Plugin Enable Flow

The enablePluginInConfig() function implements the plugin enable logic:

1. Check if plugins.enabled === false (global disable). If so, return failure with reason "plugins disabled".
2. Check if the plugin ID is in plugins.deny. If so, return failure with reason "blocked by denylist".
3. Set plugins.entries.<pluginId>.enabled = true.
4. Ensure the plugin ID is in the plugins.allow list (if the list exists).
5. Return the updated config.

Skill Enable Flow

Skill enablement is determined by the shouldIncludeSkill() function and the resolveSkillConfig() lookup:

1. Look up skills.entries.<skillKey> via resolveSkillConfig().
2. If enabled === false, the skill is excluded.
3. If no entry exists, the skill defaults to enabled (subject to eligibility checks).

Allowlist and Denylist Interaction

For plugins, the deny list takes absolute precedence:

deny contains pluginId?  -->  BLOCKED (no override possible)
                         |
                         v
allow list exists?  -->  pluginId in allow?  -->  yes: eligible
                    |                        |
                    |                        v
                    |                        no: BLOCKED
                    v
                    (no allow list): eligible

The enablePluginInConfig() function automatically adds the plugin to the allow list when enabling, so that enabling a plugin also allowlists it.

For skills, there is no deny list. The skills.allowBundled list only affects bundled skills (source: openclaw-bundled). Non-bundled skills are never filtered by the bundled allowlist.

Configuration Schema Validation

Plugins can declare a config schema (JSON Schema). When a plugin's per-entry config is provided, it is validated against the schema during loading. If validation fails, the plugin enters an error state with a diagnostic message.

Skills do not have schema validation. Their config is a free-form record passed through without validation.

Related Concepts

• Extension Type Identification -- the two extension types that are configured.
• Plugin Installation -- how plugins are installed before they can be configured.
• Skill Loading -- how skill configuration affects loading and filtering.
• Extension Verification -- how configuration errors surface in the plugin registry.

Implementation

Implementation:Openclaw_Openclaw_EnablePluginInConfig