11.7 执行工具

Exec工具允许在工作空间中运行shell命令,支持前台和后台执行模式。

概述

exec工具是OpenClaw的核心功能之一,允许代理执行shell命令来完成各种任务。它支持灵活的执行模式和安全控制。

主要参数

必需参数

• command: 要执行的shell命令

可选参数

• workdir: 工作目录
• env: 环境变量
• yieldMs: 轮询间隔(默认10000ms)
• background: 后台执行
• timeout: 超时时间(默认1800秒)
• pty: 使用伪终端
• host: 执行位置(sandbox/gateway/node)
• security: 安全级别(deny/allowlist/full)
• ask: 批准模式(off/on-miss/always)
• node: 节点标识符
• elevated: 提权执行

使用示例

前台执行

{
  "tool": "exec",
  "command": "ls -la"
}

后台执行并轮询

# 启动后台任务
{
  "tool": "exec",
  "command": "npm run build",
  "yieldMs": 1000
}

# 轮询进程状态
{
  "tool": "process",
  "action": "poll",
  "sessionId": ""
}

发送按键

{
  "tool": "process",
  "action": "send-keys",
  "sessionId": "",
  "keys": ["Enter"]
}

提交输入

{
  "tool": "process",
  "action": "submit",
  "sessionId": ""
}

粘贴文本

{
  "tool": "process",
  "action": "paste",
  "sessionId": "",
  "text": "line1\\nline2\\n"
}

配置选项

{
  "tools": {
    "exec": {
      "notifyOnExit": true,
      "approvalRunningNoticeMs": 5000,
      "host": "sandbox",
      "security": "allowlist",
      "ask": "on-miss",
      "node": null,
      "pathPrepend": [],
      "safeBins": []
    }
  }
}

PATH处理

• gateway: 合并登录shell的PATH
• sandbox: 使用 sh -lc
• node: 仅应用env覆盖

会话覆盖

通过 /exec 指令设置会话级别的覆盖(需要授权):

/exec host=gateway security=allowlist

Exec批准

Exec批准需要伴侣应用或节点主机设置。如果批准待定,返回 "approval-pending"。

白名单模式

白名单仅匹配已解析的二进制路径:

• 不支持基本名称匹配
• 拒绝命令链接(;, &&, ||)
• 拒绝重定向操作

apply_patch子工具

apply_patch是一个实验性子工具,需要显式启用:

{
  "tools": {
    "exec": {
      "applyPatch": {
        "enabled": true
      }
    }
  }
}

仅支持OpenAI/Codex模型。

安全考虑

进程管理

process工具操作

• poll: 检查进程状态
• send-keys: 发送按键序列
• submit: 提交当前输入
• paste: 粘贴多行文本
• kill: 终止进程

使用场景

• 构建任务: 运行构建和编译命令
• 测试执行: 运行测试套件
• 部署操作: 执行部署脚本
• 系统管理: 系统维护和配置
• 数据处理: 批处理和数据转换