ddea4f1ae40a4099baa9f216cdae69ac35a5e93aa254903227ce168e2fd5b8db config-baseline.json

b6b71095384ad98410bbfd520eebac43e244aeb47761c74325ff133be6ccd858 config-baseline.core.json

14558f9777b400fe4a1ef163a44e90ac0c59b56920ceb24b99675647d19d73a8 config-baseline.json

0c46cd7aeae83eb3afddd19209bf3520cecccc265903b2fe001ce458bc592ea5 config-baseline.core.json

cd7c0c7fb1435bc7e59099e9ac334462d5ad444016e9ab4512aae63a238f78dc config-baseline.channel.json

9832b30a696930a3da7efccf38073137571e1b66cae84e54d747b733fdafcc54 config-baseline.plugin.json

plugins: {

enabled: true,

allow: ["voice-call"],

bundledMode: "compat",

bundledDiscovery: "compat",

deny: [],

load: {

paths: ["~/Projects/oss/voice-call-plugin"],

- Discovery accepts native OpenClaw plugins plus compatible Codex bundles and Claude bundles, including manifestless Claude default-layout bundles.

- **Config changes require a gateway restart.**

- `allow`: optional allowlist (only listed plugins load). `deny` wins.

- `bundledMode`: defaults to `"compat"` for legacy bundled provider activation.

Use `"respect-allow"` when a non-empty `plugins.allow` should also gate

- `bundledDiscovery`: defaults to `"compat"` for legacy bundled provider activation.

Use `"allowlist"` when a non-empty `plugins.allow` should also gate

bundled provider plugins, including web-search runtime providers.

- `plugins.entries.<id>.apiKey`: plugin-level API key convenience field (when supported by the plugin).

- `plugins.entries.<id>.env`: plugin-scoped env var map.

Doctor also warns when `plugins.allow` is non-empty and tool policy uses

wildcard or plugin-owned tool entries. `tools.allow: ["*"]` only matches tools

from plugins that actually load; it does not bypass the exclusive plugin

allowlist.

allowlist. If bundled provider discovery is still in legacy compatibility

mode, doctor also points to the stricter `plugins.bundledDiscovery:

"allowlist"` setting.

</Accordion>

<Accordion title="2. Legacy config key migrations">

}

```

| Field | Description |

| ---------------- | --------------------------------------------------------- |

| `enabled` | Master toggle (default: `true`) |

| `allow` | Plugin allowlist (optional) |

| `bundledMode` | Bundled plugin allowlist mode (`compat` by default) |

| `deny` | Plugin denylist (optional; deny wins) |

| `load.paths` | Extra plugin files/directories |

| `slots` | Exclusive slot selectors (e.g. `memory`, `contextEngine`) |

| `entries.\<id\>` | Per-plugin toggles + config |

| Field | Description |

| ------------------ | --------------------------------------------------------- |

| `enabled` | Master toggle (default: `true`) |

| `allow` | Plugin allowlist (optional) |

| `bundledDiscovery` | Bundled plugin discovery mode (`compat` by default) |

| `deny` | Plugin denylist (optional; deny wins) |

| `load.paths` | Extra plugin files/directories |

| `slots` | Exclusive slot selectors (e.g. `memory`, `contextEngine`) |

| `entries.\<id\>` | Per-plugin toggles + config |

`plugins.allow` is exclusive. When it is non-empty, only listed plugins can load

or expose tools, even if `tools.allow` contains `"*"` or a specific plugin-owned

tool name. If a tool allowlist references plugin tools, add the owning plugin ids

to `plugins.allow` or remove `plugins.allow`; `openclaw doctor` warns about this

shape.

`plugins.bundledMode` defaults to `"compat"` so older configs keep legacy

bundled provider behavior. Set it to `"respect-allow"` when a restrictive

`plugins.bundledDiscovery` defaults to `"compat"` so older configs keep legacy

bundled provider behavior. Set it to `"allowlist"` when a restrictive

`plugins.allow` inventory should also block omitted bundled provider plugins,

including runtime web-search provider discovery. An empty `plugins.allow` is

still treated as unset/open.

).toEqual(["kilocode", "moonshot", "openrouter"]);

});

it("respects allowlist for bundled plugins when bundledMode is respect-allow", () => {

it("respects allowlist for bundled plugins when bundledDiscovery is allowlist", () => {

const config = withBundledPluginEnablementCompat({

config: withBundledPluginAllowlistCompat({

config: {

plugins: {

allow: ["openrouter"],

bundledMode: "respect-allow",

bundledDiscovery: "allowlist",

},

},

pluginIds: ["kilocode", "moonshot"],

}));

}

const { collectPluginToolAllowlistWarnings } =

const { collectBundledProviderAllowlistPolicyWarnings, collectPluginToolAllowlistWarnings } =

await import("./doctor/shared/plugin-tool-allowlist-warnings.js");

const pluginToolAllowlistWarnings = collectPluginToolAllowlistWarnings({

cfg: candidate,

env: process.env,

});

const pluginToolAllowlistWarnings = [

...collectPluginToolAllowlistWarnings({

cfg: candidate,

env: process.env,

}),

...collectBundledProviderAllowlistPolicyWarnings({ cfg: candidate }),

];

if (pluginToolAllowlistWarnings.length > 0) {

note(sanitizeDoctorNote(pluginToolAllowlistWarnings.join("\n")), "Doctor warnings");

}

import { describe, expect, it } from "vitest";

import type { PluginManifestRegistry } from "../../../plugins/manifest-registry.js";

import { collectPluginToolAllowlistWarnings } from "./plugin-tool-allowlist-warnings.js";

import {

collectBundledProviderAllowlistPolicyWarnings,

collectPluginToolAllowlistWarnings,

} from "./plugin-tool-allowlist-warnings.js";

const manifestRegistry: PluginManifestRegistry = {

diagnostics: [],

expect(warnings).toEqual([]);

});

it("warns when restrictive plugins.allow leaves bundled provider discovery in compat mode", () => {

const warnings = collectBundledProviderAllowlistPolicyWarnings({

cfg: {

plugins: { allow: ["telegram"] },

},

});

expect(warnings).toEqual([

expect.stringContaining('set plugins.bundledDiscovery to "allowlist"'),

]);

});

it("does not warn when bundled provider discovery follows the allowlist", () => {

const warnings = collectBundledProviderAllowlistPolicyWarnings({

cfg: {

plugins: {

allow: ["telegram"],

bundledDiscovery: "allowlist",

},

},

});

expect(warnings).toEqual([]);

});

});

return warnings;

}

export function collectBundledProviderAllowlistPolicyWarnings(params: {

cfg: OpenClawConfig;

}): string[] {

if (params.cfg.plugins?.enabled === false) {

return [];

}

const allow = params.cfg.plugins?.allow;

if (!Array.isArray(allow) || allow.length === 0) {

return [];

}

if (params.cfg.plugins?.bundledDiscovery === "allowlist") {

return [];

}

return [

'- plugins.allow is restrictive, but bundled provider discovery is still in legacy compatibility mode. Bundled provider plugins can still appear in runtime provider inventories; set plugins.bundledDiscovery to "allowlist" after confirming omitted bundled providers are intentionally blocked.',

];

}

description:

"Per-plugin settings keyed by plugin ID including enablement and plugin-specific runtime configuration payloads. Use this for scoped plugin tuning without changing global loader policy.",

},

bundledMode: {

bundledDiscovery: {

type: "string",

enum: ["compat", "respect-allow"],

title: "Bundled Plugin Mode",

enum: ["compat", "allowlist"],

title: "Bundled Plugin Discovery",

description:

'Controls whether bundled plugins bypass plugins.allow on runtime discovery paths. "compat" (default) preserves legacy behavior where bundled provider plugins are force-loaded on every chat turn. "respect-allow" gates bundled plugins by the allowlist the same way third-party plugins are gated.',

'Controls bundled plugin runtime discovery when plugins.allow is configured. "compat" (default) preserves legacy behavior where bundled provider plugins can be force-loaded on every chat turn. "allowlist" gates bundled provider plugins by plugins.allow like third-party plugins.',

},

},

additionalProperties: false,

help: "Optional allowlist of plugin IDs; when set, only listed plugins are eligible to load. Configured bundled chat channels can still activate their bundled plugin when the channel is explicitly enabled in config. Use this to enforce approved extension inventories in controlled environments.",

tags: ["access"],

},

"plugins.bundledMode": {

label: "Bundled Plugin Mode",

help: 'Controls whether bundled plugins bypass plugins.allow on runtime discovery paths. "compat" (default) preserves legacy behavior where bundled provider plugins are force-loaded on every chat turn. "respect-allow" gates bundled plugins by the allowlist the same way third-party plugins are gated.',

"plugins.bundledDiscovery": {

label: "Bundled Plugin Discovery",

help: 'Controls bundled plugin runtime discovery when plugins.allow is configured. "compat" (default) preserves legacy behavior where bundled provider plugins can be force-loaded on every chat turn. "allowlist" gates bundled provider plugins by plugins.allow like third-party plugins.',

tags: ["advanced"],

},

"plugins.deny": {

'Select the active memory plugin by id, or "none" to disable memory plugins.',

"plugins.slots.contextEngine":

"Selects the active context engine plugin by id so one plugin provides context orchestration behavior.",

"plugins.bundledMode":

'Controls whether bundled plugins bypass plugins.allow on runtime discovery paths. "compat" (default) preserves legacy behavior where bundled provider plugins are force-loaded on every chat turn. "respect-allow" gates bundled plugins by the allowlist the same way third-party plugins are gated.',

"plugins.bundledDiscovery":

'Controls bundled plugin runtime discovery when plugins.allow is configured. "compat" (default) preserves legacy behavior where bundled provider plugins can be force-loaded on every chat turn. "allowlist" gates bundled provider plugins by plugins.allow like third-party plugins.',

"plugins.entries":

"Per-plugin settings keyed by plugin ID including enablement and plugin-specific runtime configuration payloads. Use this for scoped plugin tuning without changing global loader policy.",

"plugins.entries.*.enabled":