OpenClaw v2026.3.31 Kills nodes.run: What the Unified Execution Model Means for Your Agents

OpenClaw v2026.3.31 removes the duplicated nodes.run shell wrapper entirely, forcing all node shell execution through the unified exec host=node pathway while reserving nodes invoke for node-specific capabilities. This breaking change eliminates a long-standing architectural inconsistency where developers could accidentally bypass security controls by using the wrong execution primitive. If you maintain OpenClaw deployments, your automation scripts will fail immediately upon upgrade unless you migrate shell commands to the new unified model. The release also hardens gateway authentication, disables node commands until explicit pairing approval, and switches installation security to fail-closed by default, marking a significant shift toward zero-trust agent execution.

What Exactly Changed in Node Execution?

The nodes.run command is gone. Completely removed from the CLI and the agent nodes tool. Previously, you had two ways to execute shell commands on a node: the generic exec host=node pathway and the node-specific nodes.run wrapper. This duplication created confusion about which path respected security boundaries and which capabilities were available in each context. OpenClaw v2026.3.31 consolidates everything into exec host=node for shell execution.

Node-specific capabilities have not disappeared. They have moved to nodes invoke and dedicated action paths for media, location, and notifications. This separation enforces a cleaner architecture: shell execution happens through the standardized exec interface, while node-resident features use the invoke API. The change affects both manual CLI usage and programmatic agent tool calls. If your agents currently call nodes.run to restart services or check disk space, those calls will return errors after upgrading. You need to rewrite those tool invocations to use the exec pathway with explicit host targeting.

Why Did OpenClaw Remove nodes.run?

Technical debt accumulated around the dual-path execution model. The nodes.run wrapper existed as a convenience method that bypassed some of the security auditing built into the main exec pipeline. Maintaining two code paths for shell execution meant double the attack surface and inconsistent logging. The OpenClaw maintainers chose to consolidate rather than patch the divergence.

Security unification drove this decision. The exec host=node pathway supports comprehensive audit logging, permission scoping, and session isolation that nodes.run only partially implemented. By forcing all shell execution through a single hardened path, OpenClaw eliminates the risk of developers accidentally using the less secure wrapper for critical operations. This aligns with the broader v2026.3.31 theme of reducing trusted surfaces and requiring explicit authentication. The removal also simplifies the mental model: you no longer need to remember which wrapper supports which flags or security contexts.

The Technical Migration Path for Developers

You need to audit every instance of nodes.run in your codebase. Start with shell scripts and cron jobs that call the OpenClaw CLI. Replace openclaw nodes run --target=node1 --command="systemctl restart agent" with openclaw exec host=node1 -- systemctl restart agent. Notice the syntax shift from a flag-based command to positional arguments after the host specifier.

For agent configurations, update your tool definitions. If you have a tool schema that calls nodes.run, change the function name to exec and add host=node as the first parameter. Test in a staging environment first because exit codes and output formatting may differ slightly between the old wrapper and the new exec pathway. The nodes.run wrapper sometimes modified exit codes to handle node connection failures differently than standard shell execution. Your error handling logic might need adjustment if you depend on specific non-zero exit codes.

How exec host=node Changes Your Security Model

The unified execution model enforces stricter authentication than the old nodes.run wrapper. Every exec host=node call now requires valid session tokens and respects the gateway’s trusted-proxy settings. You cannot execute commands on paired nodes without explicit authorization, even from the same host. This closes a loophole where local processes could execute remote shell commands using cached node credentials without re-authentication.

Permission scoping becomes mandatory. The exec pathway checks tool permissions against the agent’s declared capability manifest. If your agent tries to execute a shell command that is not listed in its allowed tools, the gateway rejects the request. Previously, nodes.run sometimes bypassed these checks through legacy compatibility shims. Audit your agent manifests to ensure they declare shell execution capabilities explicitly. Add exec:shell or specific command patterns to the tools array in your agent configuration files.

Breaking Down the nodes.invoke vs exec host=node Split

Understanding the new dichotomy is crucial for proper architecture. Use exec host=node when you need standard shell execution: running binaries, manipulating files, managing processes. This pathway treats the node as a generic compute host. Use nodes invoke when you need node-specific capabilities that require local context: accessing hardware sensors, triggering node-resident skills, or managing node-local state.

The dedicated action paths handle special categories. Media capture, location services, and notifications each have their own optimized pathways that do not require shell execution privileges. Do not try to execute arecord or notify-send through exec host=node if you can use the native media or notify actions. The native paths include proper error handling, resource management, and security sandboxing that raw shell execution lacks. This separation prevents agents from accidentally bricking nodes with poorly formatted shell commands when high-level APIs exist.

Gateway/Node Command Approval Requirements

Node commands now stay disabled until explicit pairing approval. Previously, completing device pairing automatically exposed declared node commands to the gateway. This created a window where malicious or malfunctioning nodes could execute commands before administrative review. v2026.3.31 adds an explicit approval step.

After pairing a new node, you must run openclaw gateway nodes approve --node-id=<id> before any commands execute. Check your automation scripts that provision new nodes. If you have CI/CD pipelines that pair nodes and immediately execute setup commands, they will fail with a “node commands disabled” error. Add the approval step to your provisioning playbooks. The approval requirement applies to both programmatic API calls and manual CLI usage. You can check approval status with openclaw gateway nodes list --pending-approval.

Trusted-Proxy Authentication Changes

The trusted-proxy configuration now rejects mixed shared-token setups. You cannot configure some proxies with shared tokens and others with individual authentication in the same gateway instance. This prevents downgrade attacks where an attacker compromises a shared-token proxy to impersonate individual users.

Local-direct fallback requires explicit tokens. Previously, connections from localhost bypassed token validation, assuming same-host implied same-trust. This assumption fails in containerized environments where multiple isolated processes share the host network namespace. Now you must configure the authentication token even for local-direct fallback connections. Update your local development setups to include proper token configuration in ~/.config/openclaw/gateway.yaml. The change breaks existing local debugging workflows but eliminates a significant privilege escalation vector.

Plugin SDK Deprecation Timeline

The legacy provider compatibility subpaths are deprecated. If you import from openclaw/plugin-sdk/compat or use the older bundled provider setup, you will see migration warnings in your build logs. The channel-runtime compatibility shims will be removed in a future major release.

Migrate to the documented openclaw/plugin-sdk/* entrypoints immediately. Use the local api.ts and runtime-api.ts barrels for type definitions. The new SDK structure provides better tree-shaking and smaller bundle sizes. Update your package.json imports to reference the specific submodules you need rather than importing from the root compat layer. The warnings include specific migration paths for each deprecated import. Address them now to avoid breaking builds when v2027.x removes the shims entirely.

Fail-Closed Installation Security

Built-in dangerous-code critical findings now fail closed by default. Previously, installing plugins or gateway-backed skills with critical security findings required a warning acknowledgment but allowed completion. v2026.3.31 blocks installation entirely unless you explicitly override.

Use --dangerously-force-unsafe-install only after manual code review. This flag applies to both openclaw skills install and openclaw plugins install commands. Your automated deployment pipelines might break if they install community plugins that have not been updated to pass the new security scanners. Audit your dependencies before upgrading. The scanner detects hardcoded credentials, unsafe eval usage, and unauthorized network egress patterns. Fix these issues upstream or fork the plugins internally rather than overriding security in production.

ACPX Plugin Tools and MCP Bridge Hardening

The ACPX plugin-tools MCP bridge now defaults to off. You must explicitly enable it in your gateway configuration to expose OpenClaw tools to MCP clients. This prevents accidental exposure of agent capabilities to unauthorized Model Context Protocol connections.

Documentation now clarifies the trust boundary between OpenClaw agents and MCP clients. The built-in bridge packaging uses hardened logging paths that work reliably with global installs and stdio MCP sessions. If you use Claude Desktop or other MCP clients with OpenClaw, update your bridge configuration to explicitly enable the interface. Set acpx.mcp_bridge.enabled: true in your gateway config and specify allowed tool prefixes to limit exposure. The hardening fixes path traversal vulnerabilities in previous versions where MCP clients could request arbitrary file access through poorly sanitized tool parameters.

Impact on Existing Node-Triggered Flows

Node-originated runs operate on a reduced trusted surface. If you have notification-driven flows or node-triggered automation that previously relied on broad host or session tool access, they will fail with permission errors. The gateway now restricts what tools a node-originated run can invoke, even if the node is properly paired and approved.

Review your event handlers. Flows triggered by node events like disk_full or hardware_alert need explicit tool declarations in their handler definitions. Add a tools: section to your event handler YAML specifying exactly which commands the handler can execute. This prevents compromised nodes from pivoting to broader infrastructure access through event callbacks. Test your monitoring automations thoroughly after upgrading. The reduced surface might break legitimate alerting workflows that assumed implicit broad access.

Comparing Old vs New Node Execution Patterns

Feature	Old nodes.run	New exec host=node	nodes invoke
Shell execution	Yes	Yes	No
Authentication	Partial	Full required	Full required
Hardware access	No	No	Yes
Audit logging	Basic	Comprehensive	Comprehensive
Exit code handling	Modified	Native shell	N/A
Media/Location/Notify	No	No	Native actions
Session isolation	Limited	Strict	Strict
Pairing approval	Not required	Required	Required

The table clarifies the capability split. Shell execution moves exclusively to exec host=node with full authentication and native exit codes. Node-specific hardware and sensor access requires nodes invoke. High-level actions use dedicated pathways. This eliminates the ambiguity of the old nodes.run which tried to handle both shell and node-specific tasks poorly.

Code Examples: Before and After

Before (v2026.3.30 and earlier):

# CLI usage
openclaw nodes run --target=webserver-01 --command="docker ps -a"

# Agent tool call
{
  "tool": "nodes.run",
  "params": {
    "target": "webserver-01",
    "command": "systemctl status nginx"
  }
}

After (v2026.3.31):

# CLI usage
openclaw exec host=webserver-01 -- docker ps -a

# Agent tool call
{
  "tool": "exec",
  "params": {
    "host": "webserver-01",
    "command": ["systemctl", "status", "nginx"]
  }
}

Notice the array format for commands in the new tool call format. This prevents shell injection attacks that the string-based command parameter previously allowed. Update your agent prompt templates to generate array-format commands. The -- separator in CLI usage prevents argument confusion with OpenClaw’s own flags.

What This Means for Multi-Agent Orchestration

Cross-node execution requires explicit trust establishment. If you run multi-agent systems where Agent A on Node 1 executes commands on Node 2, you must configure pairwise approvals and capability manifests for both directions. The old nodes.run wrapper allowed some implicit trust inheritance that exec host=node rejects.

Agent networks need gateway coordination. You cannot have agents directly execute shell commands on peers without going through the central gateway’s approval and audit systems. This adds latency but prevents lateral movement if one agent node is compromised. Update your orchestration playbooks to include approval steps between agent pairing and task delegation. The multi-agent orchestration hardening discussed in our previous coverage now applies to all node types, not just gateway-managed hosts.

Security Implications of Reduced Trusted Surfaces

The attack surface shrinks significantly. By removing nodes.run, OpenClaw eliminates a code path that had partial authentication checks and inconsistent audit logging. Attackers can no longer exploit the wrapper’s legacy compatibility modes to bypass security controls.

Lateral movement becomes harder. Node-originated runs with reduced tool access prevent compromised edge devices from using OpenClaw as a pivot to internal infrastructure. The fail-closed installation security blocks supply chain attacks that rely on malicious plugins executing immediately after install. However, you must update your incident response playbooks. Forensic data collection from nodes now requires explicit exec host=node permissions in your response agent’s manifest. The old nodes.run path allowed some emergency access patterns that no longer work.

When to Use nodes.invoke vs Media/Location/Notify Actions

Use nodes invoke for custom node-resident skills and hardware abstraction. If you built a custom skill that interfaces with specialized sensors or actuators, expose it through nodes invoke with a specific capability name. This keeps hardware access encapsulated and testable.

Use dedicated actions for standard services. The media, location, and notify actions provide sandboxed, user-consented access to cameras, GPS, and notification systems. Do not write shell scripts that call curl to send notifications when the notify action exists. The dedicated actions handle permission prompts, rate limiting, and error recovery. They also work when the node is in low-power modes that disable general shell execution. Check the OpenClaw skills guide for implementing custom node capabilities that integrate with the invoke pathway.

Migration Checklist for Production Deployments

1. Audit existing usage: grep -r "nodes.run" /etc/openclaw/ ~/agent-configs/ across all management hosts. This initial step is crucial for identifying all affected areas.
2. Update CLI scripts: Replace nodes run with exec host= syntax in cron jobs and systemd units. Ensure these changes are thoroughly tested in a non-production environment.
3. Migrate agent configs: Change tool definitions from nodes.run to exec with array-format commands. This update is critical for agent functionality post-upgrade.
4. Configure authentication: Add tokens to local-direct fallback configs for localhost debugging. This closes a critical security loophole.
5. Review node approvals: Run openclaw gateway nodes list --pending-approval and approve legitimate nodes. This new explicit approval step is a core security enhancement.
6. Test event handlers: Verify node-triggered flows have explicit tool declarations. Without these, your automation might silently fail.
7. Check plugin installs: Attempt installs in staging to identify dangerous-code findings before production. This preemptive check can prevent production outages due to security blocks.
8. Update SDK imports: Replace deprecated compat paths with openclaw/plugin-sdk/* entrypoints. This ensures compatibility with future OpenClaw versions and leverages performance improvements.
9. Enable MCP bridge explicitly: Set acpx.mcp_bridge.enabled: true if using Model Context Protocol. This prevents unintended exposure of tools to MCP clients.
10. Validate exit codes: Test error handling scripts that depend on specific shell exit codes. The change in how exit codes are handled can affect automation logic.

Perform these steps in a staging environment first. The exit code handling changes particularly affect automation that relies on specific non-zero return values. Thorough testing here will prevent unexpected behavior in production.

The Future of Unified Node Execution in OpenClaw

This consolidation signals OpenClaw’s move toward a zero-trust execution model. Future releases will likely extend the exec host= pattern to other resource types, creating a unified “exec resource=target” syntax for databases, APIs, and cloud services. The removal of duplicate pathways reduces maintenance burden and security exposure.

Expect stricter sandboxing. The v2026.3.31 changes lay groundwork for containerized node execution where exec host=node runs commands in isolated namespaces. The nodes invoke pathway will handle hardware passthrough with explicit capability delegation. Developers should architect their agents assuming that shell execution and node capabilities remain strictly separated. Build your skills to expose functionality through nodes invoke rather than requiring shell access. This future-proofs your deployments against further hardening of the exec pathway. This strategic direction emphasizes robust security and clear separation of concerns, ensuring OpenClaw remains a leading platform for secure and scalable AI agent deployment.

Frequently Asked Questions

Will my existing nodes.run commands break immediately after updating?

Yes. The nodes.run shell wrapper is completely removed from both CLI and agent nodes tool. Any scripts, automation, or agent configurations using nodes.run will fail with a command not found error. You must migrate to exec host=node for shell execution or nodes invoke for node-specific capabilities before deploying v2026.3.31 to production environments.

How do I handle node-triggered notification flows that stopped working?

Node-originated runs now operate on a reduced trusted surface. You need to explicitly declare broader host or session tool access in your flow definitions. If your notification-driven automation previously relied on implicit broad access, add the required tool permissions to the node event handler configuration or move the logic to a gateway-approved command context.

What’s the difference between —dangerously-force-unsafe-install and previous install behavior?

Previously, built-in dangerous-code critical findings allowed installation to succeed with warnings. Now v2026.3.31 fails closed by default. The —dangerously-force-unsafe-install flag explicitly overrides security scanning failures for plugin installs and gateway-backed skill dependencies. Only use this in isolated development environments after manual code review.

Can I still use local-direct fallback without authentication on the same host?

No. The trusted-proxy now rejects mixed shared-token configs, and local-direct fallback requires the explicitly configured token instead of implicitly authenticating same-host callers. You must configure the authentication token in your local gateway settings even for localhost connections. This closes a privilege escalation vector where same-host processes could bypass authentication.

When should I use nodes.invoke instead of exec host=node?

Use nodes.invoke for node-specific capabilities like hardware abstraction, local sensor access, or node-resident skill execution. Use exec host=node for standard shell commands, file system operations, or process management. Keep media, location, and notify actions on their dedicated action paths rather than trying to execute them through shell wrappers.