Exec 工具

在 Workspace 中运行 shell 命令。通过 process 支持前台和后台执行。如果 process 被禁用，exec 会同步运行并忽略 yieldMs/background 参数。后台 Session 的作用域限定在每个 Agent 内；process 只能看到同一个 Agent 的 Session。

参数

command（必填）
workdir（默认为当前工作目录）
env（键值对形式的环境变量覆盖）
yieldMs（默认 10000）：延迟后自动转入后台
background（布尔值）：立即转入后台
timeout（秒，默认 1800）：超时后终止进程
pty（布尔值）：在伪终端中运行（适用于仅支持 TTY 的 CLI、编码 Agent、终端 UI）
host（sandbox | gateway | node）：执行位置
security（deny | allowlist | full）：gateway/node 的安全模式
ask（off | on-miss | always）：gateway/node 的审批提示
node（字符串）：用于 host=node 时的节点 ID/名称
elevated（布尔值）：请求提升模式（gateway 主机）；只有当 elevated 解析为 full 时，security=full 才会被强制执行

注意事项：

host 默认为 sandbox。
当沙箱关闭时，elevated 会被忽略（exec 已经在主机上运行）。
gateway/node 的审批由 ~/.openclaw/exec-approvals.json 控制。
node 需要配对的节点（companion 应用或无头节点主机）。
如果有多个节点可用，设置 exec.node 或 tools.exec.node 来选择一个。
在非 Windows 主机上，exec 会使用 SHELL 环境变量（如果设置了）；如果 SHELL 是 fish，它会优先从 PATH 中选择 bash（或 sh）以避免与 fish 不兼容的脚本，如果两者都不存在则回退到 SHELL。
主机执行（gateway/node）会拒绝 env.PATH 和加载器覆盖（LD_*/DYLD_*），以防止二进制劫持或注入代码。
重要：沙箱默认是关闭的。如果沙箱关闭，host=sandbox 会直接在 Gateway 主机上运行（没有容器），并且不需要审批。要启用审批，请使用 host=gateway 并配置 exec 审批（或启用沙箱）。

配置

tools.exec.notifyOnExit（默认：true）：为 true 时，后台 exec Session 会在退出时将系统事件加入队列并请求 Heartbeat。
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：要添加到 exec 运行的 PATH 前面的目录列表。
tools.exec.safeBins：仅使用 stdin 的安全二进制文件，可以在没有明确白名单条目的情况下运行。

示例：

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

PATH 处理

host=gateway：将你的登录 shell 的 PATH 合并到 exec 环境中。主机执行会拒绝 env.PATH 覆盖。Daemon 本身仍然使用最小的 PATH：
- macOS：/opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
- Linux：/usr/local/bin、/usr/bin、/bin
host=sandbox：在容器内运行 sh -lc（登录 shell），所以 /etc/profile 可能会重置 PATH。OpenClaw 在 profile 加载后通过内部环境变量添加 env.PATH（不进行 shell 插值）；tools.exec.pathPrepend 也会在这里生效。
host=node：只有你传递的未被阻止的环境变量覆盖会发送到节点。主机执行会拒绝 env.PATH 覆盖。无头节点主机只在 PATH 添加到节点主机 PATH 前面时接受（不能替换）。macOS 节点会完全丢弃 PATH 覆盖。

为每个 Agent 绑定节点（在配置中使用 Agent 列表索引）：

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

控制界面：Nodes 标签页包含一个小的”Exec node binding”面板，用于相同的设置。

Session 覆盖（`/exec`）

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

示例：

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

授权模型

/exec 只对授权发送者有效（Channel 白名单/配对加上 commands.useAccessGroups）。它只更新 Session 状态，不会写入配置。要完全禁用 exec，通过工具策略拒绝它（tools.deny: ["exec"] 或针对每个 Agent）。除非你明确设置 security=full 和 ask=off，否则主机审批仍然适用。

Exec 审批（companion 应用 / 节点主机）

沙箱化的 Agent 可以在 exec 在 Gateway 或节点主机上运行之前要求每次请求的审批。查看 Exec 审批了解策略、白名单和 UI 流程。

当需要审批时，exec 工具会立即返回 status: "approval-pending" 和一个审批 ID。一旦批准（或拒绝/超时），Gateway 会发出系统事件（Exec finished / Exec denied）。如果命令在 tools.exec.approvalRunningNoticeMs 后仍在运行，会发出一次 Exec running 通知。

白名单 + 安全二进制文件

白名单强制执行只匹配解析后的二进制文件路径（不匹配基本名称）。当 security=allowlist 时，只有当管道的每个段都在白名单中或是安全二进制文件时，shell 命令才会自动允许。在白名单模式下，链式命令（;、&&、||）和重定向会被拒绝。

示例

前台执行：

{ "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"]}

提交（仅发送回车）：

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

粘贴（默认使用括号模式）：

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

apply_patch（实验性）

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

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