Exec Tool — Developer Reference

Type definitions, policy precedence, and implementation details for the exec tool and its approval system.

Source files

File	What it defines
`src/config/types.tools.ts`	`ExecToolConfig`, `AgentToolsConfig`, `FsToolsConfig`, `ToolsConfig`
`src/infra/exec-approvals.ts`	`ExecSecurity`, `ExecAsk`, `ExecApprovalsFile`, approval runtime
`src/config/types.approvals.ts`	`ApprovalsConfig`, `ExecApprovalForwardingConfig`
`src/config/types.agents.ts`	`AgentConfig.tools`
`src/config/types.agent-defaults.ts`	`elevatedDefault`

ExecToolConfig

// src/config/types.tools.ts
export type ExecToolConfig = {
  host?: "sandbox" | "gateway" | "node"; // default: "sandbox"
  security?: "deny" | "allowlist" | "full"; // default: "deny"
  ask?: "off" | "on-miss" | "always"; // default: "on-miss"
  node?: string;
  pathPrepend?: string[];
  safeBins?: string[];
  safeBinTrustedDirs?: string[];
  safeBinProfiles?: Record<string, SafeBinProfileFixture>;
  backgroundMs?: number;
  timeoutSec?: number;
  approvalRunningNoticeMs?: number; // agent-level only
  cleanupMs?: number;
  notifyOnExit?: boolean;
  notifyOnExitEmptySuccess?: boolean; // default: false
  applyPatch?: {
    enabled?: boolean; // default: false
    workspaceOnly?: boolean; // default: true
    allowModels?: string[];
  };
};

approvalRunningNoticeMs is only accepted on agent-level exec config (AgentToolExecSchema), not the global ToolExecSchema.

AgentToolsConfig

// src/config/types.tools.ts
export type AgentToolsConfig = {
  profile?: ToolProfileId;
  allow?: string[];
  alsoAllow?: string[];
  deny?: string[];
  byProvider?: Record<string, ToolPolicyConfig>;
  elevated?: {
    enabled?: boolean; // default: true
    allowFrom?: AgentElevatedAllowFromConfig;
  };
  exec?: ExecToolConfig;
  fs?: FsToolsConfig;
  loopDetection?: ToolLoopDetectionConfig;
  sandbox?: {
    tools?: {
      allow?: string[];
      deny?: string[];
    };
  };
};

FsToolsConfig

export type FsToolsConfig = {
  workspaceOnly?: boolean; // default: false — restrict read/write/edit/apply_patch to workspace
};

ExecApprovalsFile schema

// src/infra/exec-approvals.ts

export type ExecSecurity = "deny" | "allowlist" | "full";
export type ExecAsk = "off" | "on-miss" | "always";

export type ExecApprovalsDefaults = {
  security?: ExecSecurity;
  ask?: ExecAsk;
  askFallback?: ExecSecurity;
  autoAllowSkills?: boolean;
};

export type ExecAllowlistEntry = {
  id?: string;
  pattern: string;
  lastUsedAt?: number;
  lastUsedCommand?: string;
  lastResolvedPath?: string;
};

export type ExecApprovalsAgent = ExecApprovalsDefaults & {
  allowlist?: ExecAllowlistEntry[];
};

export type ExecApprovalsFile = {
  version: 1;
  socket?: { path?: string; token?: string };
  defaults?: ExecApprovalsDefaults;
  agents?: Record<string, ExecApprovalsAgent>;
};

Defaults at runtime:

const DEFAULT_SECURITY: ExecSecurity = "deny";
const DEFAULT_ASK: ExecAsk = "on-miss";
const DEFAULT_ASK_FALLBACK: ExecSecurity = "deny";
const DEFAULT_AUTO_ALLOW_SKILLS = false;
const DEFAULT_SOCKET = "~/.openclaw/exec-approvals.sock";
const DEFAULT_FILE = "~/.openclaw/exec-approvals.json";
export const DEFAULT_EXEC_APPROVAL_TIMEOUT_MS = 120_000;

ApprovalsConfig (approval forwarding)

// src/config/types.approvals.ts

export type ExecApprovalForwardingMode = "session" | "targets" | "both";

export type ExecApprovalForwardTarget = {
  channel: string;
  to: string;
  accountId?: string;
  threadId?: string | number;
};

export type ExecApprovalForwardingConfig = {
  enabled?: boolean; // default: false
  mode?: ExecApprovalForwardingMode; // default: "session"
  agentFilter?: string[];
  sessionFilter?: string[];
  targets?: ExecApprovalForwardTarget[];
};

export type ApprovalsConfig = {
  exec?: ExecApprovalForwardingConfig;
};

Global vs agent-level precedence

Effective exec policy is the stricter of config (tools.exec.* / agents.list[].tools.exec.*) and exec-approvals.json. Omitted approvals fields fall back to the config value. Global (tools.exec) sets the floor. Agent-level (agents.list[].tools.exec) overrides. exec-approvals.json overrides per-agent at runtime (hot-reloaded, not requiring gateway restart). Config schema uses two separate shapes:

ToolExecSchema — global, no approvalRunningNoticeMs
AgentToolExecSchema — extends base with approvalRunningNoticeMs

Tool policy filtering order

Tool availability is determined in this order (each level can only further restrict):

Tool profile (tools.profile or agents.list[].tools.profile)
Provider tool profile (tools.byProvider[provider].profile)
Global tool policy (tools.allow / tools.deny)
Provider tool policy (tools.byProvider[provider].allow/deny)
Agent-specific tool policy (agents.list[].tools.allow/deny)
Agent provider policy (agents.list[].tools.byProvider[provider].allow/deny)
Sandbox tool policy (tools.sandbox.tools or agents.list[].tools.sandbox.tools)
Subagent tool policy (tools.subagents.tools)

deny always wins. A non-empty allow makes everything not listed implicitly blocked. Tool policy is the hard stop — /exec cannot override a denied exec tool. If agents.list[].tools.sandbox.tools is set, it replaces tools.sandbox.tools for that agent.

Tool groups

Tool policies support group:* shorthands:

Group	Expands to
`group:runtime`	`exec`, `bash`, `process`
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
`group:memory`	`memory_search`, `memory_get`
`group:ui`	`browser`, `canvas`
`group:automation`	`cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`
`group:openclaw`	all built-in tools (excludes provider plugins)

Safe bin implementation

SafeBinProfileFixture defines the argv policy for a safe bin:

// src/infra/exec-safe-bin-policy-profiles.ts
export type SafeBinProfileFixture = {
  minPositional?: number;
  maxPositional?: number;
  allowedValueFlags?: readonly string[];
  deniedFlags?: readonly string[];
};

Validation is deterministic from argv shape only (no filesystem existence checks). Safe bins force argv tokens to be treated as literal text (no globbing, no $VAR expansion). Long options are fail-closed: unknown flags and ambiguous abbreviations are rejected. Default denied flags per bin:

grep: --dereference-recursive, --directories, --exclude-from, --file, --recursive, -R, -d, -f, -r
jq: --argfile, --from-file, --library-path, --rawfile, --slurpfile, -L, -f
sort: --compress-program, --files0-from, --output, --random-source, --temporary-directory, -T, -o
wc: --files0-from

Shell chaining (&&, ||, ;) is allowed only when every top-level segment satisfies the allowlist (including safe bins). Redirections are unsupported in allowlist mode. Command substitution ($() / backticks) is rejected during allowlist parsing. Safe bins must resolve from trusted directories (defaults: /bin, /usr/bin). PATH entries are never auto-trusted. Add package-manager paths via tools.exec.safeBinTrustedDirs. safeBinProfiles — per-agent profile keys override global keys.

apply_patch subtool

apply_patch is a subtool of exec for structured multi-file edits (OpenAI models only):

{
  tools: {
    exec: {
      applyPatch: { enabled: true, workspaceOnly: true, allowModels: ["gpt-5.2"] },
    },
  },
}

Tool policy: allow: ["exec"] implicitly allows apply_patch. workspaceOnly defaults to true (workspace-contained). Config lives under tools.exec.applyPatch.

Shell environment notes

OPENCLAW_SHELL=exec is set in the spawned command environment (including PTY and sandbox) so shell/profile rules can detect exec-tool context.
On non-Windows: uses SHELL; if SHELL is fish, prefers bash/sh from PATH, then falls back to fish.
On Windows: prefers PowerShell 7 (pwsh), falls back to PowerShell 5.1.
Host execution (gateway/node) rejects env.PATH and loader overrides (LD_*/DYLD_*).
Script preflight checks inspect only files inside the effective workdir boundary; paths resolving outside workdir skip preflight.

elevatedDefault

// src/config/types.agent-defaults.ts
elevatedDefault?: "off" | "on" | "ask" | "full";

Sets the default elevated level when no /elevated directive is present for a session. "full" skips exec approvals entirely. Related: Exec Tool (user) · Exec Tool (admin) · Sandboxing (developer)

Getting started

Talking to your AI

Built-in tools

Help

Users

Automation

CLI command reference

Help and FAQ

Media nodes

Setup and onboarding

Voice and realtime

More agent tools

Shohin

Exec developer

Exec Tool — Developer Reference

Source files

ExecToolConfig

AgentToolsConfig

FsToolsConfig

ExecApprovalsFile schema

ApprovalsConfig (approval forwarding)

Global vs agent-level precedence

Tool policy filtering order

Tool groups

Safe bin implementation

apply_patch subtool

Shell environment notes

elevatedDefault

​Exec Tool — Developer Reference

​Source files

​ExecToolConfig

​AgentToolsConfig

​FsToolsConfig

​ExecApprovalsFile schema

​ApprovalsConfig (approval forwarding)

​Global vs agent-level precedence

​Tool policy filtering order

​Tool groups

​Safe bin implementation

​apply_patch subtool

​Shell environment notes

​elevatedDefault

Exec Tool — Developer Reference

Source files

ExecToolConfig

AgentToolsConfig

FsToolsConfig

ExecApprovalsFile schema

ApprovalsConfig (approval forwarding)

Global vs agent-level precedence

Tool policy filtering order

Tool groups

Safe bin implementation

apply_patch subtool

Shell environment notes

elevatedDefault