What Just Happened to Node Execution in OpenClaw 2026.3.31?
The nodes.run shell wrapper is gone. As of OpenClaw 2026.3.31, node shell execution exclusively routes through exec host=node. This consolidation eliminates duplicate code paths and forces all node-level shell interactions through a single, auditable gateway. If your agents or CLI scripts rely on nodes.run to execute shell commands on paired devices, they will fail immediately upon upgrade with clear error messages indicating the removed function. The change affects both the CLI interface and the agent nodes tool, meaning every automated workflow, deployment script, and agent skill that touches node shells needs immediate attention. This is not a deprecation with a grace period. It is a hard removal that prioritizes security consistency over backward compatibility, reflecting OpenClaw’s shift toward stricter capability isolation. Node-specific capabilities like media capture, location services, and notifications remain accessible through nodes invoke and dedicated actions, but raw shell access now requires the explicit exec host=node pattern. You must audit your codebase now to identify and rectify all instances of nodes.run.
Why Did OpenClaw Remove the nodes.run Shell Wrapper?
OpenClaw maintainers eliminated nodes.run because it represented dangerous technical debt. The wrapper duplicated functionality already available through the exec host target while creating a parallel authentication and permission path that complicated security audits. Having two ways to execute shell commands on nodes meant two sets of bugs, two surfaces for privilege escalation, and inconsistent logging across distributed agent clusters. The team chose consolidation over convenience to enforce a single source of truth for node execution. By funneling everything through exec host=node, they ensure that shell-level access respects the same host-level security policies, audit trails, and capability boundaries as local execution. This change also clarifies the architectural separation between generic compute resources and node-specific hardware capabilities like cameras or GPS. The removal aligns with broader hardening efforts seen in this release, including stricter gateway authentication and reduced trust surfaces for node-originated events. Fewer code paths mean fewer vulnerabilities. This strategic decision strengthens the overall security posture of the OpenClaw ecosystem.
How Does exec host=node Replace the Old Pattern?
You need to replace nodes.run calls with exec host=node syntax. The parameter structure changes slightly. Where you previously called nodes.run("device-id", "command"), you now use exec host=node target=device-id command. The host parameter explicitly scopes the execution to the node layer, while the target parameter identifies the specific device. Environment variable passing remains similar but requires the --env flag prefix rather than positional arguments. For agents using the TypeScript SDK, replace nodes.run() method calls with exec({ host: "node", target: "device-id", command: "ls -la" }). The return structure standardizes on the exec response format, which includes exit codes, stdout, and stderr in a consistent JSON schema. This standardization means you can reuse error handling logic between local and remote execution. Update your type definitions to expect ExecResult instead of the deprecated NodeRunResult interface, ensuring your code remains type-safe and robust.
What Breaks When You Upgrade to 2026.3.31?
Your deployments will fail if you have not migrated. The CLI throws Error: Unknown command 'nodes.run' immediately when parsing old scripts. Agent skills using the JavaScript or Python SDK will encounter AttributeError: module 'openclaw' has no attribute 'nodes.run' or TypeScript compilation errors indicating the missing method. CI/CD pipelines executing remote diagnostics via openclaw nodes run will halt with exit code 1. Gateway-backed automations that trigger shell commands on paired phones or IoT devices will return 400 Bad Request errors citing invalid tool references. The failure is immediate and total for affected code paths. There is no fallback mode or compatibility shim. Additionally, if you rely on implicit authentication for local-direct gateway connections, those will now fail with 401 Unauthorized errors requiring explicit token configuration. Plugin installations containing flagged dangerous code patterns will also fail closed unless you provide the --dangerously-force-unsafe-install override flag. Node commands remain disabled until pairing approval completes, adding another potential point of failure if not addressed.
Migrating Your Existing Node Shell Scripts
Start with a global search for nodes.run across your repository. Replace CLI invocations first. Change openclaw nodes run device-abc "uptime" to openclaw exec host=node target=device-abc -- uptime. Note the double-dash separator (--) for command arguments to prevent flag parsing conflicts with the exec command itself. For SDK implementations, update import statements to remove deprecated NodeRunner classes. Refactor function calls to use the exec client with explicit host scoping. Test locally against a single node before rolling to production clusters. Update your documentation and runbooks immediately to reflect these new patterns. If you have wrapper scripts that abstracted nodes.run, collapse those layers since the new pattern is already abstracted through the unified exec interface. Verify that your error handling catches the new exception types thrown by the exec subsystem, which differ from the legacy node-specific errors. Check that environment variable injection uses the updated syntax with explicit export declarations, ensuring proper context for your remote commands.
Understanding the New Node Capability Boundaries
The removal clarifies what nodes can and cannot do. Shell execution now requires explicit host targeting, but node-specific hardware capabilities remain accessible through dedicated channels. Use nodes invoke for media capture, location retrieval, and push notifications. These actions bypass shell execution entirely, interacting directly with device APIs through sanitized bridges. This separation prevents shell injection attacks from accessing hardware functions while maintaining functionality. The exec host=node pattern is strictly for compute and file system operations. You cannot chain hardware access commands through shell strings anymore. If you previously used nodes.run to execute a script that then took a photo, you must now split that workflow. Trigger the shell script via exec, then make a separate nodes invoke media.capture call. This architectural boundary enforces least-privilege principles and simplifies compliance auditing by creating clear separation between code execution and hardware access, leading to a more secure and maintainable system.
Plugin SDK Deprecations You Cannot Ignore
The 2026.3.31 release deprecates legacy provider compatibility subpaths that many plugins still reference. If your plugin imports from openclaw/plugin-sdk/compat or uses bundled provider setup shims, you will see migration warnings in logs. These paths will disappear in the next major release. Update your imports to use the documented openclaw/plugin-sdk/* entrypoints or local api.ts and runtime-api.ts barrels. The compatibility shims for channel-runtime interactions are also marked for removal. Refactor your plugin initialization code to use the current runtime API surface. The warnings include specific file and line references to help you locate deprecated calls. Do not ignore these warnings even if functionality currently works. The next major version will break these integrations completely. Update your plugin.json manifest to specify the new SDK version requirements to prevent installation on incompatible OpenClaw versions, ensuring forward compatibility and reducing future migration effort.
The New Security Model for Dangerous Code Detection
OpenClaw now fails closed on critical security findings during skill and plugin installation. Previously, dangerous code patterns triggered warnings but allowed installation to proceed. Now, builds containing critical severity findings halt immediately. This affects automated deployments and CI pipelines that previously succeeded despite security warnings. To proceed with installation after reviewing the findings, you must append --dangerously-force-unsafe-install to your install commands. This flag applies to both openclaw skills install and openclaw plugins install operations. The security scanner runs at install time against the full dependency tree, not just top-level code. Gateway-backed skill dependencies are also subject to these scans. This change prevents compromised or vulnerable dependencies from entering production environments through transitive inclusions. Update your deployment documentation to include the override flag only for emergency scenarios after manual code review, emphasizing that its use should be exceptional and fully justified.
Gateway Authentication Changes Affecting Local Development
Local development workflows face authentication changes. The trusted-proxy configuration now rejects mixed shared-token setups, preventing configuration drift between proxy layers. More significantly, local-direct fallback no longer implicitly authenticates same-host callers. Your local OpenClaw CLI must now present the configured token even when connecting to a gateway on localhost or 127.0.0.1. This breaks scripts that relied on implicit local trust. Update your environment variables to include OPENCLAW_GATEWAY_TOKEN with the valid shared secret. Check your gateway logs for authentication failures indicating “missing token” or “invalid local-direct credentials”. This change closes a security hole where local network access implied authentication, but it requires immediate configuration updates for development teams. Ensure your .env files and secret management systems distribute the correct tokens to developer machines before upgrading, minimizing disruption to development workflows.
Node Pairing Approval Now Required for Commands
Device pairing alone no longer exposes node commands. In previous versions, pairing a device immediately made its declared commands available for invocation. Now, pairing establishes the connection, but an explicit approval step enables command execution. This two-step process prevents compromised pairing codes from immediately exposing device control surfaces. When you pair a new device via QR code or manual entry, you must subsequently approve the pairing in the gateway dashboard or via the openclaw gateway nodes approve CLI command. Until approval, the node appears in a “pending” state where it can send telemetry but cannot receive commands. This affects automation workflows that assumed immediate command availability after pairing. Update your device onboarding procedures to include the approval step. Monitor for nodes stuck in pending states that previously would have activated immediately, and integrate approval into your automated provisioning systems.
Reduced Trust Surfaces for Node-Originated Runs
Node-triggered flows now operate on a reduced trust surface. When a node initiates a run via notification or local trigger, it no longer inherits broad host or session tool access. These runs execute in a restricted context with limited capability sets. If your workflows rely on node-originated events triggering complex multi-tool operations on the host, they will fail with permission errors. You must explicitly grant capabilities to node-originated contexts through the new trust boundary configuration. This change prevents compromised nodes from pivoting to full host control. Review your notification-driven automations, particularly those triggered by mobile devices or IoT sensors. Ensure that required tools are explicitly allowlisted for node contexts rather than relying on implicit host session inheritance. Update your run configurations to specify origin_trust=node where appropriate to test restricted permissions, ensuring your automations function correctly within the new security model.
What Is the ACPX Plugin-Tools MCP Bridge?
The release introduces an explicit configuration for the ACPX plugin-tools MCP bridge, defaulting to off. This bridge allows Model Context Protocol tools to interact with OpenClaw plugins through a standardized interface. The default-off setting prevents unintended exposure of plugin capabilities to MCP clients until you explicitly configure the trust boundary. When enabled, the bridge hardens packaging and logging paths to support global installs and stdio MCP sessions reliably. This fixes previous issues where MCP sessions would fail when OpenClaw was installed globally rather than in a virtual environment. The configuration requires setting acpx_bridge_enabled: true in your gateway config and specifying allowed plugin scopes. Document the trust boundary clearly if you enable this feature, as it exposes plugin internals to external MCP consumers. This feature primarily affects developers building IDE integrations or external agent orchestrators that consume OpenClaw plugins via MCP, offering a more robust and secure connection.
Configuring Idle-Stream Timeouts for Embedded Runners
Embedded runner requests now support configurable idle-stream timeouts. This prevents stalled model streams from consuming resources indefinitely when the underlying LLM stops producing tokens but does not close the connection. Configure the timeout in your agent settings using the idle_stream_timeout_ms parameter. The default is 30000 milliseconds, but you may need shorter timeouts for high-frequency trading agents or longer ones for complex reasoning tasks. When the timeout triggers, the runner closes the stream and returns a timeout error, allowing your agent logic to retry or fail gracefully. This is particularly important for autonomous agents running 24/7 operations where hung connections previously accumulated until resource exhaustion. Update your production agent configurations to include explicit timeout values rather than relying on defaults. Monitor your logs for timeout events to identify problematic model endpoints or network instability, optimizing resource usage and agent resilience.
Comparing Old vs New Node Execution Patterns
You need to see the differences side by side to understand the migration scope. This table highlights the key changes between the deprecated nodes.run pattern and the new exec host=node approach, illustrating the shift in syntax, functionality, and security implications.
| Aspect | Old Pattern (nodes.run) | New Pattern (exec host=node) |
|---|---|---|
| CLI Syntax | openclaw nodes run <id> <cmd> | openclaw exec host=node target=<id> -- <cmd> |
| SDK Method | nodes.run(device, command) | exec({ host: "node", target, command }) |
| Return Type | NodeRunResult | ExecResult |
| Error Handling | Node-specific exceptions | Standardized exec exceptions |
| Authentication Scope | Node-specific permissions | Host-level policy enforcement |
| Logging | Separate audit trail | Unified exec logging |
| Hardware Capabilities | Implicit hardware access (deprecated) | Restricted to compute/filesystem operations |
| Security Model | Less stringent for local node access | Stricter, explicit authentication required |
| Architectural Purpose | General node interaction | Explicitly for shell/compute on node |
| Injection Protection | Limited for shell commands | Enhanced through explicit separation |
The table reveals that while syntax changes significantly, the underlying capability model actually becomes more consistent with local execution. You lose the implicit hardware access that created security vulnerabilities but gain predictable behavior aligned with host-level exec patterns, leading to a more secure and robust OpenClaw environment.
Updating Your CI/CD Pipelines for 2026.3.31
Your deployment automation requires immediate updates. Replace all openclaw nodes run commands in your GitHub Actions, GitLab CI, or Jenkins pipelines with the new exec host=node syntax. Update your base images to OpenClaw 2026.3.31 or later to ensure CLI availability. Add authentication steps that export OPENCLAW_GATEWAY_TOKEN before executing node commands, as local-direct implicit auth no longer works in containerized environments. Review your security scanning stages, as builds will now fail on critical dangerous-code findings. Decide whether to implement --dangerously-force-unsafe-install overrides for specific internal plugins or fix the underlying code patterns. Test node pairing flows to include the new approval step before attempting command execution. Update your pipeline notification webhooks to handle the reduced trust surface for node-originated events if your CI triggers depend on mobile device notifications, ensuring continuity of your automated workflows.
Testing Your Migration Before Production
Validate your changes in a staging environment before touching production nodes. Create a test matrix covering shell execution, hardware capability invocation, and error handling paths. Verify that exec host=node returns expected exit codes for successful and failed commands. Test that nodes invoke correctly handles media and location requests separately from shell commands. Confirm that unapproved nodes cannot receive commands by attempting to target a freshly paired but unapproved device. Check that your authentication tokens work for local-direct connections by temporarily disabling trusted-proxy modes. Run your full plugin install suite to identify any dangerous-code scan failures. Use the --dry-run flag where available to preview changes without executing destructive commands. Document any behavioral differences in timing or output formatting between the old and new execution paths for your specific use cases, ensuring a smooth transition to the updated OpenClaw version.
When to Use nodes invoke vs exec host=node
Choose the right tool for the job to avoid permission errors. Use exec host=node when you need general compute operations, file system access, or process management on the remote device. This includes running diagnostics, updating configuration files, or managing services. Use nodes invoke when accessing hardware-specific capabilities like cameras, microphones, GPS location, or notification systems. The invoke path provides sanitized APIs that prevent shell injection while delivering structured data. Never attempt to access hardware through shell commands via exec as this will fail on modern OpenClaw versions with capability restrictions. If your workflow requires both, orchestrate them separately. Execute the shell portion first, then invoke the hardware action, combining the results in your agent logic. This separation improves security auditability and prevents accidental hardware access by compromised shell scripts, contributing to a more robust and secure agent design.
What This Means for Multi-Node Agent Clusters
Distributed agent architectures face coordination changes. When managing fleets of edge devices, you must now handle the pairing approval bottleneck. Automated scaling scripts that pair and immediately command new nodes will fail. Insert an approval polling step or use the gateway API to programmatically approve trusted devices immediately after pairing. The unified exec interface simplifies code across your cluster since you use the same pattern for local and remote execution, but the authentication requirements mean your node management services need access to gateway tokens. The reduced trust surface for node-originated events affects decentralized decision-making patterns. Nodes can no longer trigger complex host-side workflows without explicit capability grants. Centralize sensitive operations or explicitly configure capability delegation for node contexts in your cluster orchestration layer, ensuring your multi-node deployments remain functional and secure.
Timeline for Complete Legacy Removal
These changes mark the beginning of a cleanup phase, not the end. The Plugin SDK deprecations emit warnings now but will become hard errors in the next major release, likely 2027.1.0 based on OpenClaw’s quarterly major release cycle. The nodes.run removal is immediate with no deprecation period, but other legacy patterns in the SDK have until the next major version. Plan your migration sprints accordingly. Prioritize fixing the hard breaks in 2026.3.31 immediately, then address SDK warnings over the next quarter. The dangerous-code fail-closed behavior is permanent and will not revert. Gateway authentication hardening will continue in future releases, potentially removing more implicit trust patterns. Subscribe to the OpenClaw RFC repository for advance notice of breaking changes. Tag your internal plugins and skills with compatibility metadata to prevent accidental installation on incompatible OpenClaw versions during the transition period, ensuring a smooth and predictable evolution of your OpenClaw deployments.
Frequently Asked Questions
How do I fix “Unknown command ‘nodes.run’” errors after upgrading?
You are calling the removed shell wrapper. Replace openclaw nodes run <device> <command> with openclaw exec host=node target=<device> -- <command>. In code, replace nodes.run() with exec({ host: 'node', target: device, command: cmd }). This error indicates immediate breaking change impact requiring syntax migration across all your scripts and agent skills. Check for wrapper functions or aliases that might hide the old call pattern. Update your documentation and runbooks immediately to prevent team confusion.
Why does my local OpenClaw CLI now fail with authentication errors?
Local-direct fallback no longer implicitly authenticates same-host callers. Set the OPENCLAW_GATEWAY_TOKEN environment variable to your configured shared token before running CLI commands. This change closes a security hole where localhost access previously implied authentication without credentials. Update your .env files, Docker compose secrets, and CI/CD environment variables to include valid tokens for all connections, even local development instances.
What is the difference between nodes invoke and exec host=node?
nodes invoke accesses hardware capabilities like cameras or GPS through sanitized APIs that prevent shell injection. exec host=node runs shell commands for compute and file operations on the device. They serve different architectural purposes and security boundaries. Use invoke for hardware access, exec for shell scripts. Never attempt to access hardware capabilities through shell commands as this violates the new capability isolation model and will fail.
How do I approve node pairing to enable commands?
Use openclaw gateway nodes approve <device-id> after pairing completes. Device pairing alone no longer enables command execution for security reasons. You must explicitly approve each node in the gateway dashboard or via the CLI command. This prevents compromised pairing codes from immediately controlling devices. Check that your node status shows ‘approved’ rather than ‘pending’ before attempting to send commands or execute remote scripts.
Will my existing plugins stop working in OpenClaw 2026.3.31?
Plugins using deprecated SDK paths will show warnings but continue functioning in this release. However, plugins containing critical dangerous-code findings will fail installation unless you append --dangerously-force-unsafe-install after manual review. Update your plugin imports to use the documented openclaw/plugin-sdk/* entrypoints to eliminate deprecation warnings. Legacy bundled provider setups require migration to current runtime APIs before the next major release.