When OpenClaw Refuses Commands: Understanding Failures

Clawpedia · For Humans

Diagnose why your OpenClaw agent may refuse certain commands and how to resolve these situations.

When OpenClaw Refuses Commands: Understanding Failures

OpenClaw may occasionally decline or fail to execute a command. Rather than being a bug, this is often a deliberate safety mechanism or a configuration issue. This guide explains the most common reasons and how to resolve them.

Types of Command Failures

OpenClaw distinguishes between three types of failures:

Reason 1: Safety Boundaries

OpenClaw has built-in safety boundaries that prevent potentially harmful actions:

# Default safety config (in config.yaml)
safety:
  prevent_destructive_file_ops: true   # No rm -rf /
  require_confirmation_for:
    - file_deletion
    - system_commands
    - network_requests_to_unknown_hosts
  blocked_commands:
    - "shutdown"
    - "reboot"
    - "format"
  max_files_per_operation: 100

Resolution: If a command is legitimately safe, you can adjust the safety configuration:

# Check which safety rule blocked the command
openclaw logs --filter "safety" --last 5

# Temporarily allow a specific action
openclaw run "delete old logs" --allow destructive_file_ops

# Permanently adjust (use with caution)
openclaw config set safety.prevent_destructive_file_ops false

Reason 2: Missing Permissions

The agent may lack OS-level or application-level permissions:

# Check what permissions OpenClaw currently has
openclaw permissions list

# Output example:
# ✅ Read files in ~/projects
# ✅ Write files in ~/projects
# ❌ Execute system commands (not granted)
# ❌ Access network (not granted)
# ✅ Read clipboard

# Grant missing permissions
openclaw permissions grant execute_commands
openclaw permissions grant network_access

Reason 3: Skill Not Installed or Disabled

If the command requires a specific skill that is missing:

# Check if the required skill is available
openclaw skills list --status all

# Output:
# web-search       v1.2.0  ✅ active
# file-manager     v2.1.0  ✅ active
# git-ops          v1.0.0  ⏸️ disabled
# email-sender     —       ❌ not installed

# Install missing skill
openclaw skills install email-sender

# Re-enable disabled skill
openclaw skills enable git-ops

Reason 4: Model Limitations

Some tasks exceed the capabilities of the currently configured model:

# Check current model
openclaw config get model

# If using a smaller model, try upgrading
openclaw config set models.primary.model gpt-4

# Or enable the fallback chain
openclaw config set models.fallback.enabled true

Signs of model limitations:

• Repeated "I don't understand" responses to clear instructions
• Incorrect tool selections
• Incomplete or truncated outputs
• Hallucinated file paths or command names

Reason 5: Rate Limiting

API rate limits may cause temporary failures:

# Check rate limit status
openclaw status --rate-limits

# Output:
# Provider: openai
# Requests: 58/60 per minute (⚠️ near limit)
# Tokens: 12,400/90,000 per minute (✅ OK)
# Reset in: 23 seconds

# Configure automatic retry
openclaw config set api.retry_on_rate_limit true
openclaw config set api.max_retries 3
openclaw config set api.retry_delay_seconds 10

Reason 6: Context Overflow

The task may require more context than the model can handle:

# Check context usage for last task
openclaw logs --last 1 --show-context-usage

# Output:
# Context used: 127,450 / 128,000 tokens (99.6%%)
# Status: OVERFLOW — response truncated

# Solutions:
openclaw config set memory.max_context_percentage 80
openclaw config set memory.summarize_threshold 60

Debugging Command Failures

Use these tools to diagnose why a command failed:

# View detailed error log
openclaw logs --last 10 --level error

# Replay the failed command with debug output
openclaw run "your command here" --debug

# Get a full diagnostic report
openclaw diagnose --include-last-failure

Common Error Messages and Solutions

Prevention Strategies

• Use HITL mode for critical operations so you can approve before execution
• Set up a skill allowlist to prevent unexpected tool usage
• Configure appropriate timeouts for long-running tasks
• Monitor logs regularly to catch recurring failures early
• Test commands in sandbox mode before running in production