Exec 工具

在工作区中运行 shell 命令；使用需谨慎。支持通过 process 进行前台与后台执行。若不允许 process，exec 将同步运行并忽略 yieldMs/background。后台会话按代理划分；process 仅能看到同一代理的会话。

参数

command（必填）
workdir（默认当前工作目录）
env（键值覆盖）
yieldMs（默认 10000）：延迟后自动后台
background（布尔）：立即后台
timeout（秒，默认 1800）：超时终止
pty（布尔）：在可用时在伪终端中运行（仅 TTY 的 CLI、编程代理、终端 UI）
host（sandbox | gateway | node）：执行位置
security（deny | allowlist | full）：gateway/node 的强制模式
ask（off | on-miss | always）：gateway/node 的审批提示
node（字符串）：host=node 时的节点 id/名称
elevated（布尔）：请求 elevated 模式（网关主机）；仅当 elevated 解析为 full 时强制 security=full

说明：

host 默认为 sandbox。
关闭沙箱时 elevated 被忽略（exec 已在主机上运行）。
gateway/node 审批由 ~/.clawdbot/exec-approvals.json 控制。
node 需已配对的节点（伴侣应用或无头节点主机）。
若存在多个节点，设置 exec.node 或 tools.exec.node 选择其一。
在非 Windows 主机上，若设置了 SHELL 且为 fish，exec 会优先使用 PATH 中的 bash（或 sh）以避免与 fish 不兼容的脚本，若都不存在则回退到 SHELL。
重要：沙箱默认关闭。关闭沙箱时，host=sandbox 直接在网关主机运行（无容器）且不需要审批。若要审批，请使用 host=gateway 并配置 exec 审批（或启用沙箱）。

配置

tools.exec.notifyOnExit（默认 true）：为 true 时，后台 exec 会话在退出时入队系统事件并请求心跳。
tools.exec.approvalRunningNoticeMs（默认 10000）：审批门控的 exec 运行超过此时长时发出一次“running”通知（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 环境（除非 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。Moltbot 在 profile 加载后通过内部环境变量预置 env.PATH（无 shell 插值）；tools.exec.pathPrepend 在此也生效。
host=node：仅发送你传入的 env 覆盖。仅当 exec 调用已设置 env.PATH 时 tools.exec.pathPrepend 才生效。无头节点主机仅在 PATH 预置节点主机 PATH 时接受（不替换）。macOS 节点完全忽略 PATH 覆盖。

按代理绑定节点（使用配置中的代理列表索引）：


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

Control UI：Nodes 标签页中有“Exec node binding”面板用于相同设置。

会话覆盖（/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"] 或按代理）。除非显式设置 security=full 且 ask=off，否则主机审批仍会生效。

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

沙箱代理在网关或节点主机上执行 exec 前可要求每次审批。策略、白名单与 UI 流程见 Exec 审批。当需要审批时，exec 工具会立即返回 status: "approval-pending" 和 approval id。一旦批准（或拒绝/超时），网关会发出系统事件（Exec finished / Exec denied）。若命令在 tools.exec.approvalRunningNoticeMs 后仍在运行，会发出一次 Exec running 通知。

白名单与 safe bins

白名单强制仅匹配解析后的二进制路径（无 basename 匹配）。当 security=allowlist 时，仅当每个管道段都在白名单或是 safe bin 时，shell 命令才会被自动允许。链式（;、&&、||）和重定向在 allowlist 模式下会被拒绝。

示例

前台：


{"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（实验性）

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


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

说明：仅支持 OpenAI/OpenAI Codex 模型。工具策略仍适用；allow: ["exec"] 隐含允许 apply_patch。配置位于 tools.exec.applyPatch。