工具自动化10 分钟阅读中级

完全系统访问

读写文件、运行 shell 命令、执行脚本。完全访问或沙箱运行——由你选择

你将学到

Exec 工具的核心概念和功能
如何在前台和后台运行 shell 命令
三种主机模式:sandbox、gateway 和 node
安全模式和批准机制
配置选项和会话覆盖
apply_patch 实验性功能

目录导航

Exec 工具概览

Exec 工具让 AI 代理能够在工作区中运行 shell 命令。支持前台和后台执行、伪终端(PTY)模式,以及灵活的安全控制。选择完全访问或沙箱运行——由你决定。

读写文件

通过文件系统命令访问和修改任意文件

Shell 命令

运行任意 shell 命令和脚本

沙箱隔离

可选的容器化隔离环境,保护系统安全

参数说明

Exec 工具支持以下参数:

`command (必需)`

要执行的 shell 命令

`workdir`

`env`

环境变量覆盖(键/值对)

`yieldMs (默认 10000)`

自动转到后台的延迟时间

`background (布尔值)`

立即转到后台运行

`timeout (秒,默认 1800)`

超时后终止进程

`pty (布尔值)`

在伪终端中运行(适用于 TTY-only CLI、编码代理、终端 UI)

`host (sandbox | gateway | node)`

执行位置选择

`security (deny | allowlist | full)`

gateway/node 的强制模式

`ask (off | on-miss | always)`

gateway/node 的批准提示

`node (字符串)`

host=node 时使用的节点 ID/名称

`elevated (布尔值)`

请求提升模式(gateway 主机),仅当 security=full 时强制

配置选项

通过 ~/.openclaw/openclaw.json 配置 Exec 工具行为:

~/.openclaw/openclaw.json

tools:
  exec:
    notifyOnExit: true
    approvalRunningNoticeMs: 10000
    host: "sandbox"
    security: "deny"
    ask: "on-miss"
    pathPrepend: ["~/bin", "/opt/oss/bin"]
    safeBins: ["ls", "cat", "echo"]

tools.exec.notifyOnExit (默认: true)

当后台会话退出时,发送系统事件和心跳请求

tools.exec.approvalRunningNoticeMs (默认: 10000)

当需要批准的 exec 运行时间超过此值时,发出一次"运行中"通知(0 表示禁用)

tools.exec.host (默认: sandbox)

默认执行主机模式

tools.exec.security (默认: sandbox 为 deny,gateway/node 为 allowlist)

默认安全模式

tools.exec.ask (默认: on-miss)

默认批准行为

tools.exec.node (默认: 未设置)

默认节点选择

tools.exec.pathPrepend

要添加到 PATH 前面的目录列表

tools.exec.safeBins

无需明确允许列表即可运行的仅 stdin 安全二进制文件

主机模式

Exec 工具支持三种执行位置,每种都有不同的安全特性和用例:

sandbox

Sandbox (沙箱)

在容器中隔离运行,提供最高的安全性

•默认模式,无需批准
•文件系统访问受限
•网络访问受控
•适合不可信的代理和自动化任务

gateway

Gateway (网关主机)

在运行 Gateway 的主机上直接执行

•需要明确批准(除非配置为 security=full)
•完整的系统访问权限
•可以访问所有文件和命令
•适合需要完全控制的任务

node

Node (节点主机)

在配对的节点设备上执行

•需要配对的节点(配套应用或无头节点主机)
•支持多节点选择
•适用于远程执行和跨设备操作
•安全模式由节点配置控制

安全机制

安全模式

deny

拒绝所有命令执行(最严格,适合高安全要求)

allowlist

仅允许白名单中的命令执行(平衡安全性和灵活性)

full

允许所有命令执行(仅用于完全信任的代理)

批准机制

沙箱代理在网关或节点主机上执行 exec 前,可以要求每个请求都需要批准。批准策略存储在 ~/.openclaw/exec-approvals.json 中。

当需要批准时,exec 工具会立即返回,状态为 'approval-pending' 并包含批准 ID
批准后(或被拒绝/超时),Gateway 会发出系统事件(Exec finished / Exec denied)
如果命令运行时间超过 tools.exec.approvalRunningNoticeMs,会发出一次 Exec running 通知
在配套应用或节点主机 UI 中管理批准列表

重要提示

沙箱功能默认关闭。如果沙箱关闭,host=sandbox 会直接在 gateway 主机上运行(无容器)且不需要批准。要要求批准,请使用 host=gateway 并配置 exec 批准(或启用沙箱)。

使用示例

以下是常见的 Exec 工具使用场景:

前台执行

直接运行命令并等待完成

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

后台执行 + 轮询

启动长时间运行的任务并检查状态

{{"tool":"exec","command":"npm run build","yieldMs":1000}}
{{"tool":"process","action":"poll","sessionId":"\<id\>"}}

发送按键(tmux 风格)

与后台进程交互

{{"tool":"process","action":"send-keys","sessionId":"\<id\>","keys":["Enter"]}}
{{"tool":"process","action":"send-keys","sessionId":"\<id\>","keys":["C-c"]}}
{{"tool":"process","action":"send-keys","sessionId":"\<id\>","keys":["Up","Up","Enter"]}}

提交(仅发送 CR)

发送回车键

{{"tool":"process","action":"submit","sessionId":"\<id\>"}}

粘贴(默认使用括号)

粘贴多行文本

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

会话覆盖 (/exec)

使用 /exec 命令设置每个会话的 host、security、ask 和 node 默认值。不带参数发送 /exec 可显示当前值。

/exec host=gateway security=allowlist ask=on-miss node=mac-1

/exec 仅对授权发送者有效(频道白名单/配对加上 commands.useAccessGroups)。它只更新会话状态,不写入配置。要完全禁用 exec,请通过工具策略拒绝它。

Apply Patch (实验性)

实验性功能

apply_patch 是 exec 的子工具,用于结构化多文件编辑。需要显式启用。

tools:
  exec:
    applyPatch:
      enabled: true
      allowModels: ["gpt-5.2"]

仅适用于 OpenAI/OpenAI Codex 模型

工具策略仍然适用;allow: ["exec"] 隐式允许 apply_patch

配置位于 tools.exec.applyPatch 下

适用于批量文件编辑和代码重构

继续学习

Exec 工具只是 OpenClaw 强大功能的一部分。探索更多教程和文档:

查看全部教程访问官方文档