Skip to main content
Use this page when an agent pauses for your decision: an OpenClaw exec command waiting on a gate, or a brokered tool call / risky delegation queued for a human. Both surface in the Approvals panel, where you resolve each with Allow Once, Always, or Deny. The panel renders two distinct surfaces that look alike but are wired differently:
  • Exec Approvals: OpenClaw’s command-execution gate. Requests arrive over the live Gateway connection; you resolve them back through the Gateway, and the decision is also logged to Clawboo’s history table.
  • The shared tool-approval queue: Clawboo’s own database-mediated handshake for brokered tool calls and risky delegations. The same queue (and the same resolve buttons) is reused by the Governance dashboard, so there is one resolve path, not two.
Below those, the panel lists the broker’s tools with their availability, so you can see at a glance which tools are reachable.

​
Prerequisites

There is no standalone Approvals nav view. Approvals surface where they were raised, so you resolve them in context rather than on a separate screen. Whether anything appears at all depends on whether an agent is configured to ask before acting.
  • Approvals appear in two places, both always available:
    • The Needs approval column on the board, the first column. It collapses to a thin rail when empty and auto-expands the moment a request arrives.
    • An inline tray above the composer in group chat and 1:1 agent chat, scoped to that team or agent (capped at three cards, with a “view on the board” link for the rest).
  • For exec approvals to appear, the agent’s command-execution policy must be set to ask. Open an agent, go to the Permissions tab → Execution Permissions, and set Command Execution to Always Ask or Ask for Unknown. Then ask the agent to run a command. It pauses and the request appears here.
  • For tool / delegation approvals, no extra setup is needed; the broker writes a pending row when a risky or availability-gated tool call needs sign-off, and the governance delegation gate writes one for a risky delegation.

​
Steps

​
1. Find the pending items and read them

Both surfaces are scoped. On the board, when a team is selected, exec approvals are filtered to that team’s agents (requests with no agentId always show); selecting no team shows all. The chat tray is scoped to the team or agent you have open. Exec approvals are sorted oldest-first. Each exec approval card shows:
  • An amber “Exec Approval” label with a pulsing alert dot.
  • The owning agent’s name and a live expires Ns countdown (the Gateway times an unresolved request out after roughly 120 seconds).
  • The command in a code block, plus any of cwd, host, path, and security as detail rows, and an error line if the request carried one.
Each tool / delegation approval card (in the queue below) shows:
  • The tool name in accent red and a live expires Ns countdown.
  • An optional reason line and an optional args summary (credential-shaped fields are masked before display).

​
2. Resolve each item

Click one of the three actions on the card: What happens under the hood differs by surface:
  • Exec approval. The decision goes to the Gateway via exec.approval.resolve, then (when the agent is known) is persisted to Clawboo’s history through POST /api/approvals. The card buttons disable while the decision is in flight. After an allow, Clawboo runs a deterministic followup to recover the command’s output in webchat-only setups where the Gateway’s own delivery would otherwise drop it.
  • Tool / delegation approval. The decision is written to the tool_call_approvals row via POST /api/tools/approvals/:id/resolve. The broker (or the delegation gate) is long-polling that row in another process, so it unblocks the moment you resolve. The queue re-polls every 3 seconds, so the card clears on its own.
Resolving the same tool/delegation row twice is a no-op; the resolve is guarded on status='pending', so a stale double-click can’t flip an already-decided approval. An exec approval that has already expired Gateway-side resolves silently (the card just disappears) rather than showing a confusing error.

​
3. Watch the per-Boo indicator

While a Boo has an exec approval pending, its node in the Ghost Graph shows a pulsing amber ring, a circle when the Boo is idle, a rounded outline when it is rendered as an active card. The ring is matched by agentId, so it points at exactly the Boo waiting on you. It clears the instant you resolve.

​
What the cards report

​
Exec approval card

​
Tool / delegation card

The two surfaces write different tables and have different decision strings. Exec approvals use allow-once / allow-always / deny (with hyphens) into the approval_history log; tool/delegation approvals use allow_once / allow_always / deny (with underscores) into tool_call_approvals. The buttons read the same in the UI; the wire values differ.

​
Tool availability (read-only)

Under the queue, the panel lists every broker tool with an Available / Unavailable pill, sourced from GET /api/tools. A tool is unavailable when an availability requirement (auth, config, env, or plugin) is unmet; the card greys out and its tooltip shows the diagnostics. A non-safe risk tool also shows an amber warning icon. This is informational; there are no actions here; it tells you which brokered tools an agent can actually reach.

​
Verify it worked

  • The resolved card disappears from the board’s Needs approval column (its amber count drops by one, and the column collapses back to a thin rail once the queue empties) and from any in-chat tray. For an exec approval, the Boo’s amber ring also clears in the Ghost Graph.
  • For an exec allow, the agent resumes and (after the followup) reports the command’s output back into the chat transcript.
  • For a tool/delegation approval, the waiting tool call / delegation proceeds (on allow) or is rejected (on deny) within a few seconds.
  • The decision history is queryable: GET /api/approvals?agentId=<id> returns the persisted exec-approval decisions for that agent (most recent first).

​
Troubleshooting

A card vanished before you resolved it. Exec approvals expire Gateway-side at ~120 seconds and the queue removes expired rows; if you do not act in time, the request lapses (an exec lapse is a non-decision, not a deny). Resolve promptly, or set the agent’s policy to Ask for Unknown so only unfamiliar commands prompt.
The agent allowed a command but produced no output. In webchat-only setups the Gateway’s internal deliver:true followup can drop the output. Clawboo runs a best-effort recovery that re-sends the command with deliver:false; if it still does not land, ask the agent to run the command again.
Always is sticky. For an exec approval it allowlists the command pattern so it stops asking; for a tool/delegation it records a sticky allow for that scope. Use Allow Once when you want to keep the gate for next time.
Last modified on August 8, 2026