Exec 工具让 AI Agent 能够在工作区执行 Shell 命令，支持前台/后台运行、PTY 终端、远程节点执行，并内置完整的安全审批机制。
核心参数
| 参数 | 说明 | 默认值 |
|---|---|---|
command | 要执行的命令（必填） | — |
workdir | 工作目录 | cwd |
env | 环境变量覆盖（键值对） | — |
yieldMs | 自动转后台的等待时间（毫秒） | 10000 |
background | 立即后台运行 | false |
timeout | 超时秒数（超时后杀进程） | 1800 |
pty | 在伪终端（PTY）中运行 | false |
host | 执行位置（sandbox/gateway/node） | sandbox |
security | 安全模式（deny/allowlist/full） | — |
ask | 审批提示模式（off/on-miss/always） | on-miss |
node | 节点 ID/名称（host=node 时） | — |
elevated | 请求提升权限 | false |
三种执行位置
host=sandbox（默认）
在 Docker 沙箱中执行，与宿主机完全隔离：
json
{
"tool": "exec",
"command": "npm run build",
"host": "sandbox"
}⚠️ 沙箱默认关闭。未启用沙箱时，
host=sandbox不会静默降级到 gateway，而是直接报错。请明确启用沙箱或改用host=gateway。
host=gateway
在 Gateway 宿主机上执行，受审批机制管控：
bash
/exec host=gateway security=allowlist ask=on-misshost=node
在已配对的远程节点上执行：
bash
/exec host=node security=allowlist node=mac-1前台与后台执行
前台执行（等待完成）：
json
{"tool": "exec", "command": "ls -la"}后台执行（立即返回 session ID）：
json
{"tool": "exec", "command": "npm run build", "yieldMs": 1000}轮询后台进程：
json
{"tool": "process", "action": "poll", "sessionId": "<id>"}发送按键（tmux 风格）：
json
{"tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["Enter"]}
{"tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"]}粘贴文本（带括号保护）：
json
{"tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n"}PTY 模式
需要终端 UI 的命令（如 vim、coding agents）用 pty: true：
json
{"tool": "exec", "command": "htop", "pty": true}PATH 处理规则
- host=gateway：合并你的 login-shell PATH，但拒绝
env.PATH覆盖 - host=sandbox：通过
sh -lc运行，支持tools.exec.pathPrepend配置 - host=node：同样拒绝
env.PATH覆盖，需要通过 systemd/launchd 环境配置
预置额外 PATH（适用于 gateway 和 sandbox）：
json
{
"tools": {
"exec": {
"pathPrepend": ["~/bin", "/opt/oss/bin"]
}
}
}安全与审批机制
三种安全模式
| 模式 | 说明 |
|---|---|
deny | 拒绝所有执行 |
allowlist | 仅允许明确许可的二进制路径 |
full | 允许所有命令（高危！） |
Allowlist 管理
bash
# 添加到 allowlist
openclaw approvals allowlist add "/usr/bin/git"
openclaw approvals allowlist add --node mac-1 "/usr/bin/uname"
# 查看当前 allowlist
openclaw approvals allowlist listSafe Bins（stdin 安全过滤器）
Safe Bins 是专门为 stdin 流过滤工具设计的白名单（如 grep、jq、awk）：
json
{
"tools": {
"exec": {
"safeBins": ["grep", "jq", "awk", "sed"],
"safeBinTrustedDirs": ["/usr/local/bin"]
}
}
}⚠️ 不要把解释器（python3、node、bash）加入 safeBins，这会绕过安全检查。
Telegram 审批工作流
启用 Telegram 作为审批客户端：
json
{
"channels": {
"telegram": {
"execApprovals": {
"enabled": true,
"approvers": ["123456789"],
"target": "dm"
}
}
}
}审批流程：
- Agent 执行需要审批的命令 → 状态变为
approval-pending - 通过 Telegram 收到审批请求
- 点击批准/拒绝
- Gateway 发送
Exec finished/Exec denied系统事件
会话级覆盖（/exec）
临时修改当前 Session 的执行配置：
bash
# 切换到 gateway 执行，allowlist 模式
/exec host=gateway security=allowlist ask=on-miss node=mac-1
# 查看当前配置
/exec注意：
/exec只对授权发送者有效，只修改 session 状态，不写入配置文件。
apply_patch（实验性）
apply_patch 是 exec 的子工具，用于结构化多文件编辑（仅限 OpenAI/Codex 模型）：
json
{
"tools": {
"exec": {
"applyPatch": {
"enabled": true,
"workspaceOnly": true,
"allowModels": ["gpt-5.2"]
}
}
}
}完整配置示例
json
{
"tools": {
"exec": {
"host": "gateway",
"security": "allowlist",
"ask": "on-miss",
"node": "mac-1",
"pathPrepend": ["~/bin"],
"notifyOnExit": true,
"approvalRunningNoticeMs": 10000,
"safeBins": ["grep", "jq"],
"safeBinTrustedDirs": ["/usr/local/bin"]
}
}
}原文：Exec Tool - OpenClaw | 来源：OpenClaw 官方文档