Exec 工具

在工作区中运行 shell 命令。支持通过 ''process'' 进行前台和后台执行。

如果 ''process'' 被禁用，''exec'' 将同步运行并忽略 ''yieldMs''/''background''。

后台会话按代理范围划分；''process'' 只能看到同一代理的会话。

- ''command''（必需）

- ''workdir''（默认为 cwd）

- ''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 解析为 ''full'' 时才强制 ''full''

注意：

- ''host'' 默认为 ''sandbox''。

- 当沙箱关闭时，''elevated'' 被忽略（exec 已在主机上运行）。

- ''gateway''/''node'' 审批由 ''~/.openclaw/exec-approvals.json'' 控制。

- ''node'' 需要配对的节点（伴侣应用或无头节点主机）。

- 如果有多个节点可用，设置 ''exec.node'' 或 ''tools.exec.node'' 来选择一个。

- 在非 Windows 主机上，exec 在设置时使用 ''SHELL''；如果 ''SHELL'' 是 ''fish''，它会优先使用 ''bash''（或 ''sh''）

从 ''PATH'' 中获取，以避免 fish 不兼容的脚本，如果都不存在则回退到 ''SHELL''。

- 主机执行（''gateway''/''node''）拒绝 ''env.PATH'' 和加载器覆盖（''LD_*''/''DYLD_*''）以

防止二进制劫持或代码注入。

- 重要：沙箱''默认关闭''。如果沙箱关闭，''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 环境中。''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 通过内部环境变量在配置文件源码之后前置 ''env.PATH''（无 shell 插值）；

''tools.exec.pathPrepend'' 也适用于此处。

- ''host=node''：只有您传递的非阻止环境覆盖才会发送到节点。''env.PATH'' 覆盖

在主机执行时被拒绝。无头节点主机仅在接受 ''PATH'' 时

前置节点主机 PATH（不替换）。macOS 节点完全丢弃 ''PATH'' 覆盖。

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

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"]'' 或按代理）。除非您显式设置

''security=full'' 和 ''ask=off''，否则主机审批仍然适用。

沙箱代理可以在 ''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
line2
" }

''apply_patch'' 是 ''exec'' 的子工具，用于结构化多文件编辑。

显式启用它：

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

注意：

- 仅适用于 OpenAI/OpenAI Codex 模型。