OpenClaw 执行系统命令配置完全指南

目录

在使

用 OpenClaw 时，让 AI 助手执行系统命令（如运行脚本、调用 API）是一个常见需求。但由于安全设计，这需要正确的配置。本文将详细介绍如何安全地配置 OpenClaw 执行系统命令。

问题背景

OpenClaw 默认配置下，当你尝试让 Agent 执行命令时，可能会遇到：

1. 命令被忽略：日志显示 ignoring unprofiled safeBins entries
2. 工具未调用：Agent 只使用 memory_search 而不调用 exec
3. 执行超时：命令被调用但没有返回结果

这是因为 OpenClaw 采用了多层安全模型来控制命令执行。

安全模型概览

OpenClaw 的 exec 工具有三层安全控制：

┌─────────────────────────────────────────────────────────┐
│  Layer 1: tools.profile                                 │
│  - minimal: 仅基本工具                                  │
│  - messaging: 适合消息处理                              │
│  - coding: 开发相关工具                                 │
│  - full: 全部工具（包含 exec）                          │
├─────────────────────────────────────────────────────────┤
│  Layer 2: tools.exec.safeBins                           │
│  - 允许的二进制文件列表                                  │
│  - 解释器（python3/bash）需要 special handling          │
├─────────────────────────────────────────────────────────┤
│  Layer 3: tools.exec.safeBinProfiles                    │
│  - 每个二进制文件的详细限制                              │
│  - minPositional/maxPositional                          │
│  - allowedValueFlags/deniedFlags                        │
└─────────────────────────────────────────────────────────┘

完整配置步骤

1. 编辑配置文件

打开 ~/.openclaw/openclaw.json，添加 tools 配置：

{
  "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. 配置项详解

tools.profile

选择工具策略基线：

值	说明
minimal	仅 read/write/edit 等基本工具
messaging	适合消息处理的工具集
coding	开发相关工具（含 exec）
full	全部工具（含 browser/cron 等）

tools.exec.ask

执行前确认级别：

值	行为
off	直接执行，不询问
on-miss	不在 safeBins 时询问
always	总是询问确认

tools.exec.safeBins

允许的二进制文件列表。对于解释器（python3、bash、node 等），必须同时配置 safeBinProfiles。

tools.exec.safeBinProfiles

每个二进制文件的详细限制：

字段	说明	示例
minPositional	最小位置参数数量	1（至少1个参数）
maxPositional	最大位置参数数量	20（最多20个参数）
allowedValueFlags	允许的带值标志	["--list", "--search"]
deniedFlags	禁止的标志	["-rf", "--force"]

3. 重启 Gateway

openclaw gateway restart

4. 验证配置

测试命令执行：

openclaw agent --agent main \
  --message "用 exec 工具执行: python3 /path/to/script.py --list" \
  --local

查看日志确认：

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

你应该能看到：

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

常见场景配置示例

场景一：允许特定 Python 脚本

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

安全要点：

• 限制参数数量防止注入
• 禁止管道和重定向符号
• 只允许已知的标志

场景二：开发环境（较宽松）

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

场景三：生产环境（严格）

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

故障排查

问题 1：命令被忽略

现象：日志显示 ignoring unprofiled safeBins entries

原因：safeBins 中列出的文件不是真正的二进制文件，或没有配置 safeBinProfiles

解决：

• 对于解释器（python3、bash），必须配置 safeBinProfiles
• 对于脚本文件，使用解释器执行而非直接列出脚本

问题 2：工具未调用

现象：Agent 只使用 memory_search 而不调用 exec

原因：tools.profile 设置不正确，或未启用 exec 工具

解决：

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

问题 3：执行超时

现象：exec 被调用但没有返回

原因：默认超时时间（30秒）太短，或命令本身执行时间长

解决：

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

问题 4：参数被拒绝

现象：命令被拒绝，日志显示参数检查失败

原因：safeBinProfiles 中的 allowedValueFlags 不包含使用的标志

解决：更新 allowedValueFlags 列表，添加需要的标志

高级技巧

1. 按 Agent 配置不同权限

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

2. 使用环境变量注入密钥

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

3. 配置可信目录

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

安全最佳实践

1. 最小权限原则：只开放必要的命令和参数
2. 使用绝对路径：避免 PATH 劫持
3. 禁止危险操作：拒绝 -rf、>、|、; 等
4. 启用询问：生产环境使用 ask: "always"
5. 定期审计：检查日志中的命令执行情况

参考资料

• OpenClaw 安全文档
• Tools 配置参考
• Agent 运行时配置

---

配置版本：OpenClaw 2026.3.8

文章作者：阿文

文章链接： https://www.awen.me/post/8f139f22.html

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