<!-- source: https://deepwiki.com/openclaw/openclaw/3.4.2-exec-and-background-processes -->

# Exec & Background Processes

- docs/gateway/cli-backends.md
- docs/help/environment.md
- docs/tools/exec.md
- scripts/deadcode-unused-files.allowlist.mjs
- src/agents/acp-spawn-parent-stream.test.ts
- src/agents/acp-spawn-parent-stream.ts
- src/agents/bash-process-registry.ts
- src/agents/bash-tools.exec-host-gateway.test.ts
- src/agents/bash-tools.exec-host-gateway.ts
- src/agents/bash-tools.exec-host-node-phases.ts
- src/agents/bash-tools.exec-host-node.test.ts
- src/agents/bash-tools.exec-host-node.ts
- src/agents/bash-tools.exec-runtime.test.ts
- src/agents/bash-tools.exec-runtime.ts
- src/agents/bash-tools.exec-types.ts
- src/agents/bash-tools.exec.path.test.ts
- src/agents/bash-tools.exec.script-preflight.test.ts
- src/agents/bash-tools.exec.security-floor.test.ts
- src/agents/bash-tools.exec.ts
- src/agents/bash-tools.schemas.ts
- src/agents/bash-tools.test.ts
- src/agents/cli-output.test.ts
- src/agents/cli-output.ts
- src/agents/cli-runner.before-agent-reply-cron.test.ts
- src/agents/cli-runner.binding-flush.test.ts
- src/agents/cli-runner.context-engine.test.ts
- src/agents/cli-runner.reliability.test.ts
- src/agents/cli-runner.spawn.test.ts
- src/agents/cli-runner.ts
- src/agents/cli-runner/claude-live-session.ts
- src/agents/cli-runner/claude-skills-plugin.ts
- src/agents/cli-runner/execute.supervisor-capture.test.ts
- src/agents/cli-runner/execute.ts
- src/agents/cli-runner/log.ts
- src/agents/cli-runner/prepare.test.ts
- src/agents/cli-runner/prepare.ts
- src/agents/cli-runner/session-history.test.ts
- src/agents/cli-runner/session-history.ts
- src/agents/cli-runner/types.ts
- src/agents/command/attempt-execution.error-propagation.test.ts
- src/agents/command/attempt-execution.helpers.ts
- src/agents/command/attempt-execution.runtime.ts
- src/agents/command/attempt-execution.test.ts
- src/agents/command/claude-cli-project-dir.ts
- src/agents/exec-approval-result.test.ts
- src/agents/exec-approval-result.ts
- src/agents/mcp-oauth.ts
- src/agents/model-catalog-browse.test.ts
- src/agents/model-catalog-browse.ts
- src/agents/sessions/bash-executor.ts
- src/agents/sessions/resolve-config-value.ts
- src/agents/sessions/tools/bash.test.ts
- src/agents/sessions/tools/bash.ts
- src/agents/sessions/tools/render-utils.ts
- src/agents/shell-snapshot.test.ts
- src/agents/shell-snapshot.ts
- src/agents/shell-utils.test.ts
- src/agents/shell-utils.ts
- src/channels/draft-stream-loop.test.ts
- src/channels/draft-stream-loop.ts
- src/channels/typing-lifecycle.ts
- src/channels/typing.test.ts
- src/channels/typing.ts
- src/commands/doctor-claude-cli.test.ts
- src/commands/doctor-claude-cli.ts
- src/gateway/server-node-events.test.ts
- src/gateway/server-node-events.ts
- src/infra/exec-safe-builtins.test.ts
- src/infra/exec-safe-builtins.ts
- src/infra/heartbeat-runner.subagent-session-guard.test.ts
- src/media-understanding/runner.skip-tiny-audio.test.ts
- test/vitest/vitest.channels.config.ts

This page provides a detailed technical overview of the execution and background process tools in OpenClaw. It explains the implementation of CLI runners, shell execution on host nodes, session management, and output buffering.

## Overview

OpenClaw's execution system allows agents to interact with shell environments across multiple platforms (Host, Docker Sandbox, or Device Nodes). The system is split into two primary paradigms:

1. CLI Runners : Specialized harnesses for running LLM-native CLI tools (like claude-cli or codex-cli ) as backends for agent reasoning src/agents/cli-runner.ts 60-62
2. Bash Tools : Standard execution tools ( exec and process ) that allow agents to run arbitrary shell commands on a target host src/agents/bash-tools.exec-host-node.ts 199-200

### Key Code Entities

**Sources:** [src/agents/cli-runner.ts251](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner.ts#L251-L251) [src/agents/cli-runner/prepare.ts134-136](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner/prepare.ts#L134-L136) [src/agents/bash-tools.exec-host-node.ts199-200](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node.ts#L199-L200) [src/agents/bash-tools.exec-host-node-phases.ts177-179](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L177-L179) [src/agents/bash-process-registry.js24-31](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-process-registry.js#L24-L31) [src/agents/cli-backends.ts41](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-backends.ts#L41-L41)

## CLI Runner & Session Persistence

The `cli-runner` manages the execution of external CLI-based LLM backends. Unlike standard tools, these runners often maintain their own stateful sessions.

### Preparation Flow

Before execution, `prepareCliRunContext` builds the environment, resolves the workspace, and determines if a CLI session can be reused [src/agents/cli-runner/prepare.ts134-168](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner/prepare.ts#L134-L168)

**CLI Preparation & Execution Flow**

```

```

**Implementation Details:**

- Workspace Resolution : The system resolves the working directory via resolveRunWorkspaceDir , falling back to safe defaults if necessary src/agents/cli-runner/prepare.ts 138-144
- Session Reuse : The resolveCliSessionReuse function checks if an existing CLI process or state file matches the current context (system prompt, model, and workspace) src/agents/cli-runner/prepare.ts 42
- Transcript Persistence : User turns are recorded into session history via persistApprovedCliUserTurnTranscript only after successful execution src/agents/cli-runner.ts 200-213

**Sources:** [src/agents/cli-runner/prepare.ts134-168](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner/prepare.ts#L134-L168) [src/agents/cli-runner.ts200-213](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/cli-runner.ts#L200-L213) [src/agents/workspace-run.ts67-68](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/workspace-run.ts#L67-L68)

## Host Execution & Node Resolution

When an agent calls shell tools, OpenClaw dispatches the command to a target host. For remote or device-specific execution, it uses **Device Nodes**.

### Node Target Resolution

The `resolveNodeExecutionTarget` function identifies the specific `nodeId` from the available nodes list and ensures it is connected [src/agents/bash-tools.exec-host-node-phases.ts180-205](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L180-L205)

**Node Execution Architecture**

```

```

**Security & Approvals:**

- Preflight : Commands are analyzed to check if they hit restricted patterns or require manual user intervention src/agents/bash-tools.exec-host-node.ts 137-145
- Durable Approvals : The system checks for "allow-always" patterns in ExecAllowlistEntry to skip repetitive prompts for known safe commands src/agents/bash-tools.exec-host-node-phases.ts 99-118
- Timeout Management : Execution timeouts are strictly enforced, with resolveNodeInvokeTimeoutMs calculating safe margins for RPC overhead src/agents/bash-tools.exec-host-node-phases.ts 78-85

**Sources:** [src/agents/bash-tools.exec-host-node.ts137-145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node.ts#L137-L145) [src/agents/bash-tools.exec-host-node-phases.ts78-205](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L78-L205)

## Background Processes & Registry

OpenClaw supports long-running background processes via the `process` tool and `exec` with the `background` parameter [docs/tools/exec.md11-12](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/tools/exec.md?plain=1#L11-L12)

### Process Registry

The `bash-process-registry.js` manages the lifecycle of these backgrounded tasks [src/agents/bash-process-registry.js17-24](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-process-registry.js#L17-L24)

- Session Scoping : Background sessions are scoped per agent; the process tool only interacts with sessions belonging to the same agent docs/tools/exec.md 12
- State Management : Processes can be marked as backgrounded via markBackgrounded or exited via markExited src/agents/bash-process-registry.js 20-21
- Heartbeat Integration : When a background process exits, it can trigger a system event and request a heartbeat to notify the agent of completion src/agents/bash-tools.exec-runtime.ts 27

### Output Buffering

- Aggregation : Results from node executions are aggregated from stdout , stderr , and error fields into a single AgentToolResult src/agents/bash-tools.exec-host-node-phases.ts 155-173
- Tail Buffering : The system can notify the agent of the "tail" of output for backgrounded processes src/agents/bash-tools.exec-host-node.ts 181
- TTY Support : The pty parameter allows running commands in a pseudo-terminal for TTY-only CLIs and terminal UIs docs/tools/exec.md 40-42

**Sources:** [src/agents/bash-process-registry.js17-24](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-process-registry.js#L17-L24) [src/agents/bash-tools.exec-runtime.ts27](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-runtime.ts#L27-L27) [src/agents/bash-tools.exec-host-node-phases.ts155-173](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L155-L173) [docs/tools/exec.md11-42](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/tools/exec.md?plain=1#L11-L42)

## Configuration & Policies

Execution behavior is highly configurable through `openclaw.json` and external approval files.

- Target Hosts : Valid hosts include auto , sandbox , gateway , and node docs/tools/exec.md 44-46 auto resolves to sandbox if available, otherwise gateway src/agents/bash-tools.exec-runtime.test.ts 112-125
- Security Levels : Policies include deny , allowlist , ask , auto , and full docs/tools/exec.md 71
- Shell Snapshots : On non-Windows gateway hosts, OpenClaw captures shell aliases and functions into snapshots to ensure consistency across tool calls docs/tools/exec.md 83-87
- Path Protection : Host execution rejects env.PATH and loader overrides ( LD_* ) to prevent binary hijacking docs/tools/exec.md 88-89

**Sources:** [docs/tools/exec.md44-89](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/tools/exec.md?plain=1#L44-L89) [src/agents/bash-tools.exec-runtime.test.ts112-125](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-runtime.test.ts#L112-L125)
