在工作区中运行 Shell 命令。通过 process 支持前台和后台执行。 如果 process 被禁用，exec 将同步运行并忽略 yieldMs/background 参数。 后台会话是基于 Agent 隔离的；process 只能看到同一 Agent 的会话。

• command (必填)
• workdir (默认为 cwd)
• 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 (布尔值): 请求提升模式（网关主机）；仅当提升解析为 full 时才强制 security=full

注意：

• host 默认为 sandbox。
• 当沙盒关闭时，elevated 被忽略（exec 已经在主机上运行）。
• gateway/node 批准由 ~/.openclaw/exec-approvals.json 控制。
• node 需要配对的节点（伴侣应用或无头节点主机）。
• 如果有多个节点可用，设置 exec.node 或 tools.exec.node 来选择一个。
• 在非 Windows 主机上，exec 使用设置的 SHELL；如果 SHELL 是 fish，它会优先选择 PATH 中的 bash (或 sh) 以避免不兼容 fish 的脚本，如果都不存在则回退到 SHELL。
• 重要提示：沙盒 默认关闭。如果沙盒关闭，host=sandbox 直接在网关主机上运行（无容器），且 不需要批准。要要求批准，请使用 host=gateway 运行并配置 exec 批准（或启用沙盒）。

• tools.exec.notifyOnExit (默认: true): 当为 true 时，后台 exec 会话退出时会排队一个系统事件并请求心跳。
• 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"]
    }
  }
}

• host=gateway: 将您的登录 shell PATH 合并到 exec 环境中（除非 exec 调用已设置 env.PATH）。守护进程本身仍以最小 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: 只有您传递的环境变量覆盖会发送到节点。tools.exec.pathPrepend 仅在 exec 调用已设置 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"

控制 UI：节点选项卡包含一个用于相同设置的小型“Exec 节点绑定”面板。

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

示例：

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

/exec 仅对 授权发送者 生效（频道白名单/配对加上 commands.useAccessGroups）。 它仅更新 会话状态，不写入配置。要硬禁用 exec，请通过工具策略拒绝它（tools.deny: ["exec"] 或每个 Agent）。除非您显式设置 security=full 和 ask=off，否则主机批准仍然适用。

沙盒 Agent 在网关或节点主机上运行 exec 之前可能需要按请求批准。 请参阅 Exec 批准 了解策略、白名单和 UI 流程。

当需要批准时，exec 工具立即返回 status: "approval-pending" 和批准 ID。一旦批准（或拒绝/超时），网关会发出系统事件（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"]}

提交（仅发送 CR）：

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

粘贴（默认带括号）：

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

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

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

注意：

• 仅适用于 OpenAI/OpenAI Codex 模型。
• 工具策略仍然适用；allow: ["exec"] 隐式允许 apply_patch。
• 配置位于 tools.exec.applyPatch 下。