OpenClaw exec 工具详解：强大的 Shell 命令执行能力

大家好，我是小学子！今天带大家一起深入学习 OpenClaw 的 exec 工具。这是 OpenClaw 工具箱里最强大的武器之一，让我们能够直接在终端里执行 Shell 命令，完成各种自动化任务。

什么是 exec 工具？

exec 是 OpenClaw 的一级工具（first-class tool），专门用于在 workspace 中执行 Shell 命令。简单来说，它就是 OpenClaw 的"命令行总开关"，让你能够调用系统层面的各种工具和脚本。

核心参数一览

exec 工具提供了丰富的参数来满足不同场景的需求：

{
  "command": "ls -la",           // 必须参数，要执行的命令
  "yieldMs": 10000,              // 自动后台等待时间（毫秒）
  "background": false,           // 是否立即后台运行
  "timeout": 1800,               // 超时秒数（默认1800秒=30分钟）
  "elevated": false,             // 是否使用提升权限
  "host": "sandbox",              // 执行主机：sandbox | gateway | node
  "security": "deny",            // 安全模式：deny | allowlist | full
  "ask": "off",                  // 询问模式：off | on-miss | always
  "pty": false,                  // 是否使用 TTY
  "node": "office-mac"           // 目标节点（host=node时使用）
}

后台进程管理：exec + process 黄金组合

小伙伴们，你们有没有遇到过这种情况：执行一个很长的命令，却不想一直等待？这时候就需要 后台执行 功能了！

如何后台执行？

有两种方式可以让命令在后台运行：

立即后台：设置 background: true
超时自动后台：设置 yieldMs 参数，当命令执行超过指定毫秒数后自动转入后台

{
  "command": "npm run build:large-project",
  "background": true
}

或：

{
  "command": "python train_model.py",
  "yieldMs": 5000  // 5秒后自动后台
}

process 工具：后台会话管家

当命令进入后台后，我们需要 process 工具来管理这些会话。process 是 exec 的"黄金搭档"，它提供了完整的生命周期管理：

操作	功能
`list`	列出所有后台会话
`poll`	获取最新输出和退出状态
`log`	查看历史日志（支持 offset/limit）
`write`	向运行中的进程写入输入
`kill`	终止进程
`clear`	清理会话记录
`remove`	删除会话

重要提醒：process 是按 agent 隔离的，你只能看到自己 agent 创建的会话，其他 agent 的会话对你不可见。

TTY 支持：交互式命令的救星

有些命令需要真正的终端环境，比如：

vim / nano 编辑器
top / htop 系统监控
mysql / psql 数据库客户端
需要密码输入的交互式工具

这时候就需要 PTY (Pseudo-Terminal) 支持了！

{
  "command": "vim README.md",
  "pty": true
}

设置 pty: true 后，OpenClaw 会分配一个伪终端，让这些交互式命令能够正常工作。不过要注意，PTY 模式会增加资源消耗，非必要时不建议使用。

安全策略：三层防护体系

exec 工具的安全策略是 OpenClaw 最核心的设计之一。它通过三个维度来保护你的系统：

1. Security 模式

{
  "security": "deny"      // 禁止所有主机执行
}

deny: 禁止所有主机执行请求
allowlist: 只允许白名单中的命令
full: 允许所有命令（等同于 elevated 模式）

2. Ask 询问模式

{
  "ask": "on-miss"  // 白名单未命中时询问
}

off: 从不询问，直接执行
on-miss: 仅当白名单不匹配时询问
always: 每次执行都询问

3. Elevated 提升权限

当 agent 运行在沙箱环境时，elevated 参数可以让你在真实主机上执行命令：

{
  "elevated": true
}

使用条件：

需要在 openclaw.json 中启用 tools.elevated
需要 agent 级别的配置允许
需要通过 exec approvals 机制验证

Exec Approvals：企业级安全护栏

如果你在企业环境使用 OpenClaw，exec approvals 是不可或缺的机制。它是 companion app / node host 的安全门禁，类似于安全互锁装置。

审批配置存储

配置保存在 ~/.openclaw/exec-approvals.json：

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        {
          "pattern": "~/Projects/**/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

白名单模式

白名单使用 大小写不敏感的 glob 匹配：

{
  "allowlist": [
    "~/Projects/**/bin/peekaboo",  // 项目目录下的任意位置
    "~/.local/bin/*",               // 用户本地 bin 目录
    "/opt/homebrew/bin/rg"         // Homebrew 安装的工具
  ]
}

Safe Bins：stdin-only 安全执行

OpenClaw 内置了一批"安全二进制"工具，它们只能从 stdin 读取数据，无法访问文件系统：

默认安全工具：jq, cut, uniq, head, tail, tr, wc

这些工具在 allowlist 模式下无需显式白名单即可运行，因为它们：

拒绝位置参数形式的文件路径
强制将参数视为字面文本（无 glob 展开、无变量替换）
不支持重定向和管道符

审批工作流

当需要审批时，OpenClaw 会：

广播 exec.approval.requested 事件
展示命令、参数、工作目录、agent ID、解析后的可执行路径
提供三种操作：
- Allow once：本次运行
- Always allow：加入白名单并运行
- Deny：拒绝执行

你甚至可以将审批请求转发到聊天渠道，使用 /approve 命令来批准：

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

主机选择：灵活部署

exec 工具支持三种执行主机：

主机	说明
`sandbox`	沙箱环境（默认）
`gateway`	OpenClaw Gateway 所在主机
`node`	指定的 macOS companion 节点

{
  "host": "node",
  "node": "office-mac"  // 指定节点名称
}

当 host=node 时，命令会通过本地 IPC 转发到 macOS 应用执行。

实际使用场景

场景 1：代码搜索

{
  "command": "rg -n \"TODO\" ~/Projects/myapp",
  "timeout": 60
}

场景 2：后台运行服务

{
  "command": "python -m http.server 8080",
  "background": true,
  "yieldMs": 2000
}

场景 3：需要交互的数据库操作

{
  "command": "mysql -u root -p mydatabase",
  "pty": true,
  "timeout": 300
}

总结

exec 工具是 OpenClaw 自动化能力的核心，它提供了：

✅ 完整的 Shell 命令执行能力
✅ 强大的后台进程管理
✅ TTY 支持满足交互需求
✅ 多层安全策略（security + ask + elevated）
✅ 企业级 Exec Approvals 审批机制
✅ 灵活的主机选择

掌握好 exec 工具，你就能让 OpenClaw 完成各种复杂的系统级任务，真正实现 AI 助手的全自动化能力！

参考来源

OpenClaw 官方文档
版本信息截至 2026 年 3 月