The Complete Guide to Configuring OpenClaw to Execute System Commands

目录

When us

ing OpenClaw, having the AI assistant execute system commands (such as running scripts or calling APIs) is a common need. But due to its security design, this requires the correct configuration. This article explains in detail how to safely configure OpenClaw to execute system commands.

Problem Background

With OpenClaw’s default configuration, when you try to have the Agent execute a command, you may run into:

1. Command ignored: The log shows ignoring unprofiled safeBins entries
2. Tool not called: The Agent only uses memory_search and doesn’t call exec
3. Execution timeout: The command is called but returns no result

This is because OpenClaw uses a multi-layered security model to control command execution.

Security Model Overview

OpenClaw’s exec tool has three layers of security control:

┌─────────────────────────────────────────────────────────┐
│  Layer 1: tools.profile                                 │
│  - minimal: basic tools only                            │
│  - messaging: suited to message processing              │
│  - coding: development-related tools                    │
│  - full: all tools (including exec)                     │
├─────────────────────────────────────────────────────────┤
│  Layer 2: tools.exec.safeBins                           │
│  - the list of allowed binaries                         │
│  - interpreters (python3/bash) need special handling    │
├─────────────────────────────────────────────────────────┤
│  Layer 3: tools.exec.safeBinProfiles                    │
│  - detailed restrictions for each binary                │
│  - minPositional/maxPositional                          │
│  - allowedValueFlags/deniedFlags                        │
└─────────────────────────────────────────────────────────┘

Complete Configuration Steps

1. Edit the Configuration File

Open ~/.openclaw/openclaw.json and add the tools configuration:

{
  "tools": {
    "profile": "full",
    "exec": {
      "ask": "off",
      "timeoutSec": 60,
      "safeBins": ["python3"],
      "safeBinProfiles": {
        "python3": {
          "minPositional": 1,
          "maxPositional": 20,
          "allowedValueFlags": [
            "--list", "--search", "--json", 
            "--with-notes", "--limit", "--book-id"
          ],
          "deniedFlags": ["-rf", "--force", "--dangerous"]
        }
      }
    }
  }
}

2. Configuration Items in Detail

tools.profile

Choose the baseline tool policy:

Value	Description
minimal	Basic tools like read/write/edit only
messaging	A tool set suited to message processing
coding	Development-related tools (including exec)
full	All tools (including browser/cron, etc.)

tools.exec.ask

The confirmation level before execution:

Value	Behavior
off	Execute directly, no asking
on-miss	Ask when not in safeBins
always	Always ask for confirmation

tools.exec.safeBins

The list of allowed binaries. For interpreters (python3, bash, node, etc.), you must also configure safeBinProfiles.

tools.exec.safeBinProfiles

Detailed restrictions for each binary:

Field	Description	Example
minPositional	Minimum number of positional args	1 (at least 1 arg)
maxPositional	Maximum number of positional args	20 (at most 20 args)
allowedValueFlags	Allowed value-taking flags	["--list", "--search"]
deniedFlags	Denied flags	["-rf", "--force"]

3. Restart the Gateway

openclaw gateway restart

4. Verify the Configuration

Test command execution:

openclaw agent --agent main \
  --message "Use the exec tool to run: python3 /path/to/script.py --list" \
  --local

Check the logs to confirm:

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep exec

You should see:

exec(command="python3 /path/to/script.py --list")

Configuration Examples for Common Scenarios

Scenario One: Allow a Specific Python Script

{
  "tools": {
    "exec": {
      "ask": "off",
      "safeBins": ["python3"],
      "safeBinProfiles": {
        "python3": {
          "minPositional": 1,
          "maxPositional": 10,
          "allowedValueFlags": ["--list", "--search", "--json"],
          "deniedFlags": ["-rf", "--force", "|", ">", "<"]
        }
      }
    }
  }
}

Security points:

• Limit the number of args to prevent injection
• Ban pipe and redirection symbols
• Only allow known flags

Scenario Two: Development Environment (Looser)

{
  "tools": {
    "profile": "full",
    "exec": {
      "ask": "on-miss",
      "timeoutSec": 120,
      "safeBins": ["python3", "node", "npm"],
      "safeBinProfiles": {
        "python3": {
          "minPositional": 0,
          "maxPositional": 50
        },
        "node": {
          "minPositional": 0,
          "maxPositional": 20
        }
      }
    }
  }
}

Scenario Three: Production Environment (Strict)

{
  "tools": {
    "profile": "messaging",
    "exec": {
      "ask": "always",
      "timeoutSec": 30,
      "safeBins": ["/opt/scripts/backup.sh"],
      "safeBinProfiles": {
        "/opt/scripts/backup.sh": {
          "minPositional": 0,
          "maxPositional": 0,
          "allowedValueFlags": [],
          "deniedFlags": ["*"]
        }
      }
    }
  }
}

Troubleshooting

Problem 1: Command Ignored

Symptom: The log shows ignoring unprofiled safeBins entries

Cause: The files listed in safeBins aren’t real binaries, or safeBinProfiles isn’t configured

Fix:

• For interpreters (python3, bash), you must configure safeBinProfiles
• For script files, run them via an interpreter instead of listing the script directly

Problem 2: Tool Not Called

Symptom: The Agent only uses memory_search and doesn’t call exec

Cause: tools.profile is set incorrectly, or the exec tool isn’t enabled

Fix:

{
  "tools": {
    "profile": "full"
  }
}

Problem 3: Execution Timeout

Symptom: exec is called but doesn’t return

Cause: The default timeout (30 seconds) is too short, or the command itself takes a long time

Fix:

{
  "tools": {
    "exec": {
      "timeoutSec": 120
    }
  },
  "agents": {
    "defaults": {
      "timeoutSeconds": 120
    }
  }
}

Problem 4: Arguments Rejected

Symptom: The command is rejected and the log shows an argument check failed

Cause: allowedValueFlags in safeBinProfiles doesn’t include the flags being used

Fix: Update the allowedValueFlags list, adding the flags you need

Advanced Tips

1. Configure Different Permissions per Agent

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "profile": "full",
          "exec": {
            "ask": "off",
            "safeBins": ["python3"]
          }
        }
      },
      {
        "id": "guest",
        "tools": {
          "profile": "minimal",
          "exec": {
            "ask": "always"
          }
        }
      }
    ]
  }
}

2. Inject Secrets via Environment Variables

{
  "skills": {
    "entries": {
      "weread": {
        "env": ["KMS_MASTER_KEY", "DEEPSEEK_API_KEY"]
      }
    }
  }
}

3. Configure Trusted Directories

{
  "tools": {
    "exec": {
      "safeBinTrustedDirs": [
        "/home/wenjun/wereading_crontab",
        "/opt/scripts"
      ]
    }
  }
}

Security Best Practices

1. Least privilege: Only expose the necessary commands and arguments
2. Use absolute paths: Avoid PATH hijacking
3. Ban dangerous operations: Reject -rf, >, |, ;, etc.
4. Enable asking: Use ask: "always" in production
5. Audit regularly: Check command execution in the logs

Reference Materials

• OpenClaw security documentation
• Tools configuration reference
• Agent runtime configuration

---

Configuration version: OpenClaw 2026.3.8

中英对照

文章作者：阿文

文章链接： https://www.awen.me/post/197f39f4.html

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 阿文的博客！