Approval Gates & Safety Guardrails

+15 Mana ✨
OpenClaw Safety & Guardrails Documentation(DOCUMENTATION)

Introduction

Powerful tools require powerful safeguards. OpenClaw implements multiple layers of safety through execution security modes, approval prompts, loop detection, and elevated mode controls. This lesson covers how these mechanisms prevent agents from running harmful commands or getting stuck in unproductive cycles.

Key Concepts

  • tools.exec.security: A configuration field that sets the security mode for the exec tool, controlling how commands are vetted.
  • tools.exec.ask: A flag that requires human approval before executing any command.
  • Loop Detection: An automated system that identifies three patterns — generic repeat, poll-no-progress, and ping-pong loops.
  • Warning Threshold: The first level of loop detection that alerts the agent it may be stuck.
  • Critical Threshold: The second level that strongly warns and suggests alternative approaches.
  • Circuit Breaker: The final level that halts execution entirely to prevent resource waste.
  • Elevated Mode: A special execution mode accessed via tools.exec.elevated that runs commands with higher privileges.

Real World Context

Imagine an agent tasked with deploying a service. Without guardrails, it might repeatedly run a failing kubectl apply command, never recognizing the cluster is unreachable. Loop detection catches this poll-no-progress pattern, escalates through warning and critical thresholds, and eventually triggers the circuit breaker — stopping the agent and surfacing the issue to a human operator.

Deep Dive

Execution Security Modes

The tools.exec.security field controls how commands are evaluated before execution:

json
{
  "tools": {
    "exec": {
      "security": "strict"
    }
  }
}

This sets the execution security to strict mode. In strict mode, every command is evaluated against a set of rules before it runs. Commands that modify system state, access sensitive files, or use elevated privileges receive additional scrutiny. Other security modes offer different balances between safety and convenience.

Approval Prompts

The ask flag adds a human-in-the-loop checkpoint:

json
{
  "tools": {
    "exec": {
      "ask": true
    }
  }
}

When ask is set to true, the agent pauses before every exec call and presents the command to a human for approval. The human can approve, modify, or reject the command. This is especially valuable during initial setup or when an agent is operating in a new environment where its behavior has not yet been validated.

Combining security and ask provides defense in depth:

json
{
  "tools": {
    "exec": {
      "security": "strict",
      "ask": true
    }
  }
}

With both enabled, commands must first pass the security evaluation and then receive human approval. Either check alone can block execution.

Loop Detection

OpenClaw monitors agent behavior for three patterns that indicate unproductive loops:

Generic Repeat: The agent issues the same tool call with the same parameters multiple times in succession.

Call 1: exec "npm test"  → FAIL
Call 2: exec "npm test"  → FAIL
Call 3: exec "npm test"  → FAIL   ← Warning threshold
Call 4: exec "npm test"  → FAIL   ← Critical threshold
Call 5: exec "npm test"  → BLOCKED ← Circuit breaker

The above illustrates how repeated identical calls escalate through the three thresholds.

Poll-No-Progress: The agent repeatedly checks a condition that never changes, such as polling a service that is down.

Call 1: exec "curl http://service/health"  → Connection refused
Call 2: exec "curl http://service/health"  → Connection refused
Call 3: exec "curl http://service/health"  → Connection refused  ← Warning

This pattern is detected when the agent polls the same endpoint and receives the same error.

Ping-Pong: Two actions alternate without making progress, such as writing a file and then reverting it:

Call 1: write config.yaml (version A)
Call 2: write config.yaml (version B)
Call 3: write config.yaml (version A)  ← Detected

The system recognizes the oscillation between two states and intervenes.

Escalation Thresholds

Loop detection uses three escalation levels:

Warning     →  Agent receives a soft alert suggesting it may be stuck
Critical    →  Agent receives a strong warning with alternative suggestions
Circuit Breaker →  Execution is halted; human intervention required

Each threshold is configurable. The defaults are tuned to catch genuine loops while allowing legitimate retries, such as waiting for a service to come online.

Elevated Mode

Some operations require higher privileges:

json
{
  "tool": "exec",
  "command": "systemctl restart nginx",
  "elevated": true
}

The elevated flag runs the command with escalated permissions, similar to sudo. This flag is subject to both the security mode and the ask prompt. In strict security mode with ask enabled, an elevated command requires double confirmation — first from the security evaluation and then from the human operator.

The exec Tool Options

The full set of exec options provides fine-grained control:

json
{
  "tool": "exec",
  "command": "python train.py",
  "yieldMs": 10000,
  "background": true,
  "timeout": 300000,
  "elevated": false,
  "host": "worker-1",
  "security": "strict",
  "ask": true,
  "pty": false
}

This configuration runs a Python training script on a specific host, backgrounds it after 10 seconds, sets a 5-minute timeout, uses strict security with human approval, and disables pseudo-terminal allocation. Each option addresses a specific operational concern.

Common Pitfalls

  • Disabling ask in production: Running without approval prompts in production environments removes the human safety net. Keep ask enabled for any agent operating on production systems.
  • Ignoring loop detection warnings: The warning threshold is a signal to change strategy, not to continue. Agents should handle warnings by trying alternative approaches.
  • Overusing elevated mode: Running everything with elevated: true defeats the purpose of privilege separation. Only use it when the command genuinely requires higher permissions.

Best Practices

  • Enable both security and ask for new agents: Until you have validated an agent's behavior, use both safeguards together.
  • Handle loop detection programmatically: Design agent logic to detect when it receives a loop warning and switch to an alternative strategy.
  • Audit elevated command usage: Log and review all commands that run with elevated: true to ensure they are necessary and appropriate.

Summary

  • The tools.exec.security field sets the security mode for command execution, with strict providing the most scrutiny.
  • The tools.exec.ask flag adds human-in-the-loop approval before any command runs.
  • Loop detection catches three patterns: generic repeat, poll-no-progress, and ping-pong.
  • Escalation moves through warning, critical, and circuit breaker thresholds.
  • Elevated mode grants higher privileges but requires additional approval in strict security configurations.
✓ Completed