OpenClaw v2026.3.22 shipped on March 22, 2026, with a hard pivot toward secure plugin distribution that breaks existing workflows. The release changes how openclaw plugins install resolves packages, now checking ClawHub before npm for any npm-safe package name. This is not just a preference tweak; it is a breaking change that affects how you install, update, and trust third-party extensions. Alongside this shift, the team removed legacy Chrome extension relay support, killed the bundled nano-banana-pro image generation skill, and completely restructured the plugin SDK surface from openclaw/extension-api to openclaw/plugin-sdk/*. If you run production agents, you need to migrate immediately to ensure continued operation and security.
What Changed in OpenClaw v2026.3.22?
OpenClaw v2026.3.22 introduces six distinct breaking changes that fundamentally alter how you install, configure, and extend the framework. The most visible change affects plugin installation: bare package names now resolve against ClawHub before npm, reversing the previous default behavior. Browser automation sees the complete removal of the legacy Chrome extension relay, including the driver: "extension" configuration option and the browser.relayBindHost parameter. Image generation shifts from the bundled nano-banana-pro skill wrapper to the native image_generate tool, requiring configuration updates in your agent defaults. The plugin SDK surface migrates from the monolithic openclaw/extension-api to granular openclaw/plugin-sdk/* subpaths. Message discovery for channel adapters now requires implementing describeMessageTool(...) instead of the legacy listActions, getCapabilities, and getToolSchema methods. Finally, bundled plugins must adopt injected runtime patterns for host-side operations, removing direct import access to internal APIs. Each change requires active migration for existing deployments to prevent service disruptions.
Why Is ClawHub Now the Default for Plugin Installation?
Supply chain attacks on npm have become too common for a framework that runs autonomous AI agents with file system access. ClawHub offers cryptographically signed packages, namespace verification, and immutable version pinning that npm cannot guarantee. By checking ClawHub first, OpenClaw ensures that when you run openclaw plugins install @clawteam/security-scan, you get the official package, not a typosquatted version with a cryptominer. The fallback to npm remains for legacy packages not yet mirrored, but the default preference signals that the ecosystem is maturing beyond the wild west of unverified JavaScript packages. This mirrors moves by other frameworks to curate their own registries for critical infrastructure, such as Python’s PyPI moving towards signed packages. The change specifically targets npm-safe names, meaning any package that could legally exist on npm gets checked against ClawHub first. This prevents namespace collisions where a malicious actor might publish a package to npm after seeing it referenced in OpenClaw documentation or examples. Teams can now configure strict registries that block npm entirely, relying solely on ClawHub’s audited index for maximum security.
How Does the New Plugin Resolution Order Work?
Previously, openclaw plugins install <package> queried npm directly unless you explicitly prefixed with clawhub:. Now the logic runs: OpenClaw first checks ClawHub for the exact npm-safe name. If found and the version matches, the package is installed from ClawHub. Only if the package is not found on ClawHub or the specified version is unavailable there, does it fall back to npm. This happens transparently for bare names like openclaw-skill-websearch. If you need to force npm resolution immediately, you must use the npm: prefix explicitly, though this is discouraged for security reasons. The change affects automated CI/CD pipelines that assumed npm-first resolution. Update your deployment scripts to pin versions using openclaw plugins install package@version which respects the new resolution order while ensuring reproducible builds. The resolution logic also respects semantic versioning constraints differently; ClawHub enforces stricter compatibility checks before returning a package, whereas npm might resolve to a wider range based on dependency declarations. This means your builds become more deterministic but might fail if you had loose version constraints that previously resolved to incompatible npm versions.
What Are the Security Implications of Preferring ClawHub?
The shift to ClawHub as the primary source closes several critical attack vectors. ClawHub packages are built from reproducible sources and signed with framework-maintained keys, preventing the substitution attacks common in compromised npm accounts. The registry also enforces two-factor authentication for all publishers and conducts automated scans for known vulnerabilities before indexing and making packages available. For teams running OpenClaw’s security modules like AgentWard or ClawShield, this means your policy enforcement can now whitelist ClawHub origins exclusively, blocking npm entirely if desired and significantly reducing your attack surface. The fallback to npm is a necessary escape hatch for edge cases, but it logs a security warning in the agent runtime logs, prompting review of why a package lacks ClawHub verification. Additionally, ClawHub implements provenance attestation, linking each package to its source repository and build pipeline. This allows you to verify that the code running in your agents matches the public source, a critical feature for regulated industries and those with stringent compliance requirements. The npm fallback now requires explicit opt-in via configuration flags in secure mode, preventing accidental installations from unverified sources.
How Do You Migrate Existing Plugin Installations?
First, audit your current environment with openclaw plugins list --json to capture all installed versions and their sources. This provides a baseline for your migration. Next, check which of these packages exist on ClawHub using openclaw plugins search <name> for each identified package. For any package available on both registries, reinstall it using openclaw plugins install <name> to switch the source to ClawHub. This ensures you are leveraging the enhanced security features. Update your clawproject.json or package.json dependencies to use explicit version pins, rather than broad ranges, to ensure consistent installations. If you have custom skills referencing nano-banana-pro, replace them with the native image_generate configuration. Finally, run openclaw doctor to verify no legacy SDK imports or configuration relics remain. Commit the updated lockfile to ensure your team pulls from the correct registry. For teams with dozens of agents, consider scripting this audit using the JSON output piped to jq to filter for packages with npm provenance. Migrate in waves: start with non-production agents to verify ClawHub package behavior matches your expectations before rolling out to critical systems. Remember that ClawHub packages might have different transitive dependency trees than their npm counterparts, so test thoroughly for integration issues and potential runtime conflicts.
What Happened to the Chrome Extension Relay?
The legacy Chrome extension relay path is definitively removed. OpenClaw has eliminated the bundled extension assets, the driver: "extension" configuration option, and the browser.relayBindHost setting from the framework. This component was always a temporary solution: a browser extension bridging to the local agent via WebSocket, which introduced latency and a substantial attack surface. The development team cited maintenance burden and significant security concerns as the primary reasons for its removal. If you were using this for local browser automation, your configuration is now invalid and will throw errors on agent startup, requiring immediate attention. The CDP (Chrome DevTools Protocol) remains available and is the supported path going forward for Docker, headless, sandbox, and remote browser flows. The extension relay required maintaining separate code paths for Chrome’s constantly evolving extension API changes and manifest version updates, which diverted valuable resources from core agent development and security enhancements. Users relying on this method were essentially running a local server inside a browser extension, which created a pivot point for potential cross-site scripting (XSS) attacks or other vulnerabilities if the extension was compromised or improperly configured.
How Do You Fix Browser Configuration with openclaw doctor?
Run openclaw doctor --fix immediately after upgrading to OpenClaw v2026.3.22. This command is designed to detect host-local browser configurations that are still using the deprecated extension driver and automatically migrates them to the supported existing-session or user modes. The existing-session mode connects to a pre-existing, running Chrome instance via CDP, while user mode launches Chrome with specific user data directories, providing a consistent environment. For Docker, headless, or remote browser grid setups, no changes are needed as raw CDP connections continue to function as before. The fix command updates your claw.config.js or claw.config.yaml automatically, commenting out the old relayBindHost entries and inserting the correct browser.host and browser.port settings for direct CDP communication. If you had custom WebSocket ports configured for the extension relay, the doctor will alert you to remove these firewall rules as they are no longer necessary and represent a potential open port. The tool also verifies that your Chrome version supports the required CDP protocol version, prompting you to upgrade if you are running an outdated browser that might not be compatible. Always back up your configuration files before running any automatic fix to ensure you have a rollback point.
What Changed in Image Generation Tools?
The nano-banana-pro skill wrapper is completely removed from the OpenClaw distribution. This bundled skill provided image generation capabilities through an external API wrapper, but its existence conflicted with OpenClaw’s strategic move towards native image_generate tool standardization. All old sample-skill configurations and documentation references pertaining to nano-banana-pro have been deleted. If you had copied the nano-banana-pro configuration into your project or relied on its presence, your agents will now fail to start with a “skill not found” error, necessitating an immediate configuration update. The core framework now handles image generation directly through the powerful image_generate tool, which supports multiple providers including the newly integrated Google Gemini 3 Pro Image Preview model. This change significantly reduces dependency hell by removing an unnecessary layer of abstraction (a wrapper around an external API). The removal also eliminates a potential point of failure where the wrapper service could go offline or change its API independently of the OpenClaw release cycle, leading to unexpected outages. Native tool integration provides better error handling, more consistent retry logic, and unified authentication through the framework’s credential store rather than requiring separate API keys managed by a skill wrapper, streamlining operational overhead.
How Do You Update Image Generation Configuration?
To adapt to the changes in image generation, you must replace any YAML or JSON configuration blocks referencing nano-banana-pro with the native agents.defaults.imageGenerationModel structure. Set the primary model to google/gemini-3-pro-image-preview for the closest equivalent functionality, or choose another supported provider that aligns with your requirements. This configuration now belongs directly in your agent defaults, not in a separate skill file or plugin configuration. For example, in your claw.config.yaml, you would add or modify the following section:
agents:
defaults:
imageGenerationModel:
primary: "google/gemini-3-pro-image-preview"
# You can also specify fallback models or other provider-specific settings here
# fallbacks:
# - "openai/dall-e-3"Remove any imports, tool registrations, or environment variables that were specific to the old nano-banana-pro skill. Test image generation with a simple prompt to verify the native tool initializes correctly and produces the expected output without the wrapper overhead. You should also remove any environment variables previously required for the nano-banana-pro API keys, as the native image_generate tool uses the framework’s built-in credential management system, which offers enhanced security and centralized control. Update your internal documentation and agent playbooks to reflect that image generation is now a core feature of the OpenClaw framework rather than an installed, third-party skill.
What Is the New Plugin SDK Structure?
The monolithic openclaw/extension-api import is deprecated and removed. The new public surface for plugin development utilizes granular subpaths under openclaw/plugin-sdk/*, such as openclaw/plugin-sdk/runtime or openclaw/plugin-sdk/ui. This architectural change prevents plugins from importing internal APIs that are subject to frequent changes without notice, improving stability and reducing the likelihood of unexpected breakage. Bundled plugins must now use the injected runtime for host-side operations, accessing methods like api.runtime.agent.runEmbeddedPiAgent through the context object provided to the plugin rather than direct, hardcoded imports. This inversion of control allows the host to sandbox plugin permissions more effectively, monitor API usage, and enforce security policies. The change aligns with the framework’s broader move toward stricter capability-based security models, as seen in OpenClaw’s AgentWard and G0 modules. Each subpath exports a minimal, well-defined surface area, making it easier for bundlers to tree-shake unused code and significantly reducing the attack surface of plugins. The runtime injection pattern means plugins cannot initialize dangerous operations until the host explicitly provides the capability, preventing malicious or buggy plugins from running amok during the loading phase.
| Feature | Old SDK (openclaw/extension-api) | New SDK (openclaw/plugin-sdk/*) |
|---|---|---|
| Primary Import Path | openclaw/extension-api | openclaw/plugin-sdk/core, openclaw/plugin-sdk/runtime, openclaw/plugin-sdk/ui, etc. |
| Runtime Access | Direct module import and function calls | Injected api object provided to plugin context |
| Host Operations | Direct method calls from imported modules | api.runtime.agent.*, api.runtime.system.* |
| Manifest Validation | Loose, primarily based on plugin.json | Strict, validates capabilities field against new SDK exports |
| Security Model | Implicit trust based on module imports | Explicit capability declaration and runtime sandboxing |
| API Surface Area | Broad, potentially exposing internal APIs | Granular, minimal surface for each subpath |
| Dependency Management | Less explicit, greater risk of internal API coupling | More explicit, enforced through plugin.json declarations |
How Do You Migrate from extension-api to plugin-sdk?
To migrate your plugins, you need to systematically search your codebase for existing import statements like from "openclaw/extension-api" or require("openclaw/extension-api"). Replace these with specific subpaths under openclaw/plugin-sdk/* based on the functionality you are using. For example, runtime operations should now import from openclaw/plugin-sdk/runtime. UI components should be sourced from openclaw/plugin-sdk/ui. Messaging adapters will import from openclaw/plugin-sdk/messaging. If you were directly accessing file system operations or agent control methods, you must refactor these to use the injected api object provided in the plugin context. For instance, consider the following transformation:
// Old way: Direct import and call
import { runAgent } from "openclaw/extension-api";
async function myOldPluginAction() {
const result = await runAgent("my-pi-agent", { prompt: "do something" });
console.log(result);
}
// New way: Using the injected API object
// The 'api' object is passed to your plugin's main function or method
interface PluginContext {
api: {
runtime: {
agent: {
runEmbeddedPiAgent: (agentId: string, options: any) => Promise<any>;
};
// Other runtime APIs
};
// Other API services like ui, messaging, etc.
};
}
async function myNewPluginAction(context: PluginContext) {
const result = await context.api.runtime.agent.runEmbeddedPiAgent("my-pi-agent", { prompt: "do something" });
console.log(result);
}The extensive SDK migration documentation provides a complete mapping table for all deprecated APIs. You will also need to update your plugin.json manifest to explicitly declare which SDK subpaths you intend to use. This allows the host to validate permissions at load time, ensuring your plugin only accesses the necessary capabilities. Test your plugin thoroughly in a sandboxed environment first, as the new SDK enforces stricter runtime permissions that might throw errors where the old API silently succeeded, potentially exposing hidden bugs or security vulnerabilities.
What Changed in Message Discovery for Plugins?
OpenClaw v2026.3.22 significantly revamps how plugins expose actions and capabilities to messaging channels. Plugin authors must now implement a single, unified method: ChannelMessageActionAdapter.describeMessageTool(...) for shared message tool discovery. The previous methods, namely listActions(), getCapabilities(), and getToolSchema(), are removed without any backward compatibility shims. This change mandates a standardized interface for how agents discover what tools a plugin provides via messaging channels, streamlining the interaction process. The new describeMessageTool method returns a structured description that includes the tool’s schema, its required capabilities (permissions), and the corresponding action handlers in a single, atomic call. This design reduces the “chatty” back-and-forth communication between the host and the plugin during initialization and prevents potential race conditions where capabilities might have been checked before schemas were fully registered. Update your adapter classes to implement this new interface immediately to maintain compatibility. The consolidation also simplifies caching strategies for the OpenClaw host, as it can now cache the complete tool description rather than making multiple, separate calls to build a comprehensive picture of available actions. This change specifically affects plugins integrating with popular messaging platforms such as Slack, Discord, or custom message buses that rely on dynamic tool discovery.
How Do You Update ChannelMessageActionAdapter Implementations?
To update your ChannelMessageActionAdapter implementations, you must first remove your old listActions() method, which typically returned an array of action names. Similarly, getCapabilities() and getToolSchema() methods are no longer supported and should be removed. In their place, you will implement a single describeMessageTool(toolName: string) method that returns an object containing the schema, capabilities, and handler for the specified tool. For example, instead of the host calling adapter.listActions() to get a list of tools and then adapter.getToolSchema(name) for each, the host now makes a single call: adapter.describeMessageTool(name). This change affects any plugin that registers tools for Slack, Discord, or any custom message bus integrations. Update your unit tests to mock the new method signature to ensure your tests remain valid. The TypeScript types provided in openclaw/plugin-sdk/messaging will automatically flag the old methods as errors during compilation, guiding your migration process. It is crucial to ensure your implementation handles the case where a toolName does not exist by returning null or throwing a specific error that the host can gracefully catch, preventing unexpected crashes. The new describeMessageTool method should be idempotent and avoid side effects, as the host may call it multiple times during session initialization or when re-evaluating available tools, so it should consistently return the same valid description for a given tool name.
What Other Breaking Changes Should You Watch For?
Beyond the headline items, several other implicit behavior changes and stricter enforcements have been introduced in OpenClaw v2026.3.22. The removal of browser.relayBindHost not only invalidates configurations but also affects any custom network setups you might have had for the extension relay, requiring a review of firewall rules or proxy settings. The nano-banana-pro removal breaks any hardcoded skill IDs or direct references in your agent configurations, demanding a switch to the native image_generate tool. The SDK changes are profound, impacting not just import paths but also how you structure plugin manifests; the capabilities field in plugin.json now has stricter validation rules against the new SDK exports, meaning previously valid but overly broad declarations might now fail. Additionally, the plugin installer now rigorously respects .clawignore files when resolving local plugin paths, which might inadvertently skip files or directories that were previously included in your plugin bundles. Review the full changelog on the OpenClaw website for a comprehensive list of all changes and edge cases, especially if you run highly customized agent setups with forked or internally developed plugins. The logging format for plugin installation has also been updated to explicitly indicate the source registry (ClawHub or npm), which might break any parsing scripts or log analysis tools that expected the old npm-centric output format. Check your monitoring dashboards and log aggregators if they rely on specific log patterns for plugin installation events.
How Do You Upgrade to OpenClaw v2026.3.22 Safely?
A phased and cautious approach is best when upgrading to OpenClaw v2026.3.22 due to the extensive breaking changes. Begin by explicitly pinning your current OpenClaw version in your production environment to prevent accidental upgrades. Then, set up a dedicated staging environment that mirrors your production setup as closely as possible. Inside this staging environment, initiate the upgrade process. You can upgrade by running npm install -g openclaw@2026.3.22 for global installations, or by pulling the new Docker image openclaw/openclaw:2026.3.22 if you are using containerized deployments.
Once the new version is installed, immediately execute openclaw doctor to identify any breaking configuration issues specific to your setup. This command will provide a diagnostic report. Following that, run openclaw doctor --fix to automatically migrate detected browser settings and other common configuration issues. This will address the removal of the Chrome extension relay and update your browser automation configurations.
Next, manually audit all your installed plugins using openclaw plugins list --json and compare them against the ClawHub registry using openclaw plugins search <name>. Reinstall plugins where a ClawHub version is available to leverage the enhanced security. Update your clawproject.json or package.json to reflect the new plugin sources and explicit version pins.
Review your agent configurations for any references to nano-banana-pro and update them to use the native agents.defaults.imageGenerationModel. Finally, thoroughly test all your agents and plugins in the staging environment. Pay close attention to browser automation, image generation, and any custom plugins that interact with the SDK or messaging channels. Monitor logs for new warnings or errors that indicate compatibility issues. Only after comprehensive testing and verification in staging should you plan a rollout to your production environment, ideally during a low-traffic period with a clear rollback plan.