Exec approvals — advanced

Advanced exec-approval topics: the

fast-path, interpreter/runtime binding, and approval-forwarding to chat channels (including native delivery). For the core policy and approval flow, see Exec approvals.

Safe bins (stdin-only)

defines a small list of stdin-only binaries (for example ) that can run in allowlist mode without explicit allowlist entries. Safe bins reject positional file args and path-like tokens, so they can only operate on the incoming stream. Treat this as a narrow fast-path for stream filters, not a general trust list.

Default safe bins:

, , , , ,

and are not in the default list. If you opt in, keep explicit allowlist entries for their non-stdin workflows. For in safe-bin mode, provide the pattern with /; positional pattern form is rejected so file operands cannot be smuggled as ambiguous positionals.

Argv validation and denied flags

Validation is deterministic from argv shape only (no host filesystem existence checks), which prevents file-existence oracle behavior from allow/deny differences. File-oriented options are denied for default safe bins; long options are validated fail-closed (unknown flags and ambiguous abbreviations are rejected).

Denied flags by safe-bin profile:

• text

  Copy

  grep
  :
  text

  Copy

  --dereference-recursive
  ,
  text

  Copy

  --directories
  ,
  text

  Copy

  --exclude-from
  ,
  text

  Copy

  --file
  ,
  text

  Copy

  --recursive
  ,
  text

  Copy

  -R
  ,
  text

  Copy

  -d
  ,
  text

  Copy

  -f
  ,
  text

  Copy

  -r
• text

  Copy

  jq
  :
  text

  Copy

  --argfile
  ,
  text

  Copy

  --from-file
  ,
  text

  Copy

  --library-path
  ,
  text

  Copy

  --rawfile
  ,
  text

  Copy

  --slurpfile
  ,
  text

  Copy

  -L
  ,
  text

  Copy

  -f
• text

  Copy

  sort
  :
  text

  Copy

  --compress-program
  ,
  text

  Copy

  --files0-from
  ,
  text

  Copy

  --output
  ,
  text

  Copy

  --random-source
  ,
  text

  Copy

  --temporary-directory
  ,
  text

  Copy

  -T
  ,
  text

  Copy

  -o
• text

  Copy

  wc
  :
  text

  Copy

  --files0-from

Safe bins also force argv tokens to be treated as literal text at execution time (no globbing and no

expansion) for stdin-only segments, so patterns like or cannot be used to smuggle file reads.

Trusted binary directories

Safe bins must resolve from trusted binary directories (system defaults plus optional

). entries are never auto-trusted. Default trusted directories are intentionally minimal: , . If your safe-bin executable lives in package-manager/user paths (for example , , , ), add them explicitly to .

Shell chaining, wrappers, and multiplexers

Shell chaining (

, , ) is allowed when every top-level segment satisfies the allowlist (including safe bins or skill auto-allow). Redirections remain unsupported in allowlist mode. Command substitution ( / backticks) is rejected during allowlist parsing, including inside double quotes; use single quotes if you need literal text.

On macOS companion-app approvals, raw shell text containing shell control or expansion syntax (

, , , , , , , , , ) is treated as an allowlist miss unless the shell binary itself is allowlisted.

For shell wrappers (

), request-scoped env overrides are reduced to a small explicit allowlist (, , , , , ).

For

decisions in allowlist mode, known dispatch wrappers (, , , , ) persist the inner executable path instead of the wrapper path. Shell multiplexers (, ) are unwrapped for shell applets (, , etc.) the same way. If a wrapper or multiplexer cannot be safely unwrapped, no allowlist entry is persisted automatically.

If you allowlist interpreters like

or , prefer so inline eval still requires an explicit approval. In strict mode, can still persist benign interpreter/script invocations, but inline-eval carriers are not persisted automatically.

Safe bins versus allowlist

Configuration location:

• text

  Copy

  safeBins
  comes from config (
  text

  Copy

  tools.exec.safeBins
  or per-agent
  text

  Copy

  agents.list[].tools.exec.safeBins
  ).
• text

  Copy

  safeBinTrustedDirs
  comes from config (
  text

  Copy

  tools.exec.safeBinTrustedDirs
  or per-agent
  text

  Copy

  agents.list[].tools.exec.safeBinTrustedDirs
  ).
• text

  Copy

  safeBinProfiles
  comes from config (
  text

  Copy

  tools.exec.safeBinProfiles
  or per-agent
  text

  Copy

  agents.list[].tools.exec.safeBinProfiles
  ). Per-agent profile keys override global keys.
• allowlist entries live in host-local
  text

  Copy

  ~/.openclaw/exec-approvals.json
  under
  text

  Copy

  agents.<id>.allowlist
  (or via Control UI /
  text

  Copy

  openclaw approvals allowlist ...
  ).
• text

  Copy

  openclaw security audit
  warns with
  text

  Copy

  tools.exec.safe_bins_interpreter_unprofiled
  when interpreter/runtime bins appear in
  text

  Copy

  safeBins
  without explicit profiles.
• text

  Copy

  openclaw doctor --fix
  can scaffold missing custom
  text

  Copy

  safeBinProfiles.<bin>
  entries as
  text

  Copy

  {}
  (review and tighten afterward). Interpreter/runtime bins are not auto-scaffolded.

Custom profile example:

json5
Copy
{
  tools: {
    exec: {
      safeBins: ["jq", "myfilter"],
      safeBinProfiles: {
        myfilter: {
          minPositional: 0,
          maxPositional: 0,
          allowedValueFlags: ["-n", "--limit"],
          deniedFlags: ["-f", "--file", "-c", "--command"],
        },
      },
    },
  },
}

If you explicitly opt

into , OpenClaw still rejects the builtin in safe-bin mode so cannot dump the host process environment without an explicit allowlist path or approval prompt.

Interpreter/runtime commands

Approval-backed interpreter/runtime runs are intentionally conservative:

• Exact argv/cwd/env context is always bound.
• Direct shell script and direct runtime file forms are best-effort bound to one concrete local file snapshot.
• Common package-manager wrapper forms that still resolve to one direct local file (for example
  text

  Copy

  pnpm exec
  ,
  text

  Copy

  pnpm node
  ,
  text

  Copy

  npm exec
  ,
  text

  Copy

  npx
  ) are unwrapped before binding.
• If OpenClaw cannot identify exactly one concrete local file for an interpreter/runtime command (for example package scripts, eval forms, runtime-specific loader chains, or ambiguous multi-file forms), approval-backed execution is denied instead of claiming semantic coverage it does not have.
• For those workflows, prefer sandboxing, a separate host boundary, or an explicit trusted allowlist/full workflow where the operator accepts the broader runtime semantics.

When approvals are required, the exec tool returns immediately with an approval id. Use that id to correlate later system events (

/ ). If no decision arrives before the timeout, the request is treated as an approval timeout and surfaced as a denial reason.

Followup delivery behavior

After an approved async exec finishes, OpenClaw sends a followup

turn to the same session.

• If a valid external delivery target exists (deliverable channel plus target
  text

  Copy

  to
  ), followup delivery uses that channel.
• In webchat-only or internal-session flows with no external target, followup delivery stays session-only (
  text

  Copy

  deliver: false
  ).
• If a caller explicitly requests strict external delivery with no resolvable external channel, the request fails with
  text

  Copy

  INVALID_REQUEST
  .
• If
  text

  Copy

  bestEffortDeliver
  is enabled and no external channel can be resolved, delivery is downgraded to session-only instead of failing.

Approval forwarding to chat channels

You can forward exec approval prompts to any chat channel (including plugin channels) and approve them with

. This uses the normal outbound delivery pipeline.

Config:

json5
Copy
{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // substring or regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

Reply in chat:

text
Copy
/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

The

command handles both exec approvals and plugin approvals. If the ID does not match a pending exec approval, it automatically checks plugin approvals instead.

Plugin approval forwarding

Plugin approval forwarding uses the same delivery pipeline as exec approvals but has its own independent config under

. Enabling or disabling one does not affect the other.

json5
Copy
{
  approvals: {
    plugin: {
      enabled: true,
      mode: "targets",
      agentFilter: ["main"],
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

The config shape is identical to

: , , , , and work the same way.

Channels that support shared interactive replies render the same approval buttons for both exec and plugin approvals. Channels without shared interactive UI fall back to plain text with

instructions.

Same-chat approvals on any channel

When an exec or plugin approval request originates from a deliverable chat surface, the same chat can now approve it with

by default. This applies to channels such as Slack, Matrix, and Microsoft Teams in addition to the existing Web UI and terminal UI flows.

This shared text-command path uses the normal channel auth model for that conversation. If the originating chat can already send commands and receive replies, approval requests no longer need a separate native delivery adapter just to stay pending.

Discord and Telegram also support same-chat

, but those channels still use their resolved approver list for authorization even when native approval delivery is disabled.

For Telegram and other native approval clients that call the Gateway directly, this fallback is intentionally bounded to "approval not found" failures. A real exec approval denial/error does not silently retry as a plugin approval.

Native approval delivery

Some channels can also act as native approval clients. Native clients add approver DMs, origin-chat fanout, and channel-specific interactive approval UX on top of the shared same-chat

flow.

When native approval cards/buttons are available, that native UI is the primary agent-facing path. The agent should not also echo a duplicate plain chat

command unless the tool result says chat approvals are unavailable or manual approval is the only remaining path.

If a native approval client is configured but no native runtime is active for the originating channel, OpenClaw keeps the local deterministic

prompt visible. If the native runtime is active and attempts delivery but no target receives the card, OpenClaw sends a same-chat fallback notice with the exact command so the request can still be resolved.

Generic model:

• host exec policy still decides whether exec approval is required
• text

  Copy

  approvals.exec
  controls forwarding approval prompts to other chat destinations
• text

  Copy

  channels.<channel>.execApprovals
  controls whether that channel acts as a native approval client

Native approval clients auto-enable DM-first delivery when all of these are true:

• the channel supports native approval delivery
• approvers can be resolved from explicit
  text

  Copy

  execApprovals.approvers
  or owner identity such as
  text

  Copy

  commands.ownerAllowFrom
• text

  Copy

  channels.<channel>.execApprovals.enabled
  is unset or
  text

  Copy

  "auto"

Set

to disable a native approval client explicitly. Set to force it on when approvers resolve. Public origin-chat delivery stays explicit through .

FAQ: Why are there two exec approval configs for chat approvals?

• Discord:
  text

  Copy

  channels.discord.execApprovals.*
• Slack:
  text

  Copy

  channels.slack.execApprovals.*
• Telegram:
  text

  Copy

  channels.telegram.execApprovals.*

These native approval clients add DM routing and optional channel fanout on top of the shared same-chat

flow and shared approval buttons.

Shared behavior:

• Slack, Matrix, Microsoft Teams, and similar deliverable chats use the normal channel auth model for same-chat
  text

  Copy

  /approve
• when a native approval client auto-enables, the default native delivery target is approver DMs
• for Discord and Telegram, only resolved approvers can approve or deny
• Discord approvers can be explicit (
  text

  Copy

  execApprovals.approvers
  ) or inferred from
  text

  Copy

  commands.ownerAllowFrom
• Telegram approvers can be explicit (
  text

  Copy

  execApprovals.approvers
  ) or inferred from
  text

  Copy

  commands.ownerAllowFrom
• Slack approvers can be explicit (
  text

  Copy

  execApprovals.approvers
  ) or inferred from
  text

  Copy

  commands.ownerAllowFrom
• Slack native buttons preserve approval id kind, so
  text

  Copy

  plugin:
  ids can resolve plugin approvals without a second Slack-local fallback layer
• Matrix native DM/channel routing and reaction shortcuts handle both exec and plugin approvals; plugin authorization still comes from
  text

  Copy

  channels.matrix.dm.allowFrom
• Matrix native prompts include
  text

  Copy

  com.openclaw.approval
  custom event content on the first prompt event so OpenClaw-aware Matrix clients can read structured approval state while stock clients keep the plain-text
  text

  Copy

  /approve
  fallback
• the requester does not need to be an approver
• the originating chat can approve directly with
  text

  Copy

  /approve
  when that chat already supports commands and replies
• native Discord approval buttons route by approval id kind:
  text

  Copy

  plugin:
  ids go straight to plugin approvals, everything else goes to exec approvals
• native Telegram approval buttons follow the same bounded exec-to-plugin fallback as
  text

  Copy

  /approve
• when native
  text

  Copy

  target
  enables origin-chat delivery, approval prompts include the command text
• pending exec approvals expire after 30 minutes by default
• if no operator UI or configured approval client can accept the request, the prompt falls back to
  text

  Copy

  askFallback

Sensitive owner-only group commands such as

and use private owner routing for approval prompts and final results. OpenClaw first tries a private route on the same surface where the owner ran the command. If that surface has no private owner route, it falls back to the first available owner route from , so a Discord group command can still send the approval and result to the owner's Telegram DM when Telegram is the configured primary private interface. The group chat only gets a short acknowledgement.

Telegram defaults to approver DMs (

). You can switch to or when you want approval prompts to appear in the originating Telegram chat/topic as well. For Telegram forum topics, OpenClaw preserves the topic for the approval prompt and the post-approval follow-up.

See:

• Discord
• Telegram

macOS IPC flow

text
Copy
Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

Security notes:

• Unix socket mode
  text

  Copy

  0600
  , token stored in
  text

  Copy

  exec-approvals.json
  .
• Same-UID peer check.
• Challenge/response (nonce + HMAC token + request hash) + short TTL.

Related

• Exec approvals — core policy and approval flow
• Exec tool
• Elevated mode
• Skills — skill-backed auto-allow behavior