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（布尔）：请求提权模式（gateway 主机）；仅当提权解析�?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�?
�?Windows 主机上，exec 优先 PowerShell 7（pwsh）发现（Program Files、ProgramW6432，然�?PATH），然后回退�?Windows PowerShell 5.1�?
主机执行（gateway/node）拒�?env.PATH 和加载器覆盖（LD_*/DYLD_*）以防止二进制劫持或注入代码�?
重要：沙�?默认关闭*。如果沙箱关闭且明确配置/请求 host=sandbox，exec 现在失败关闭而不是静默在 gateway 主机上运行。启用沙箱或使用带批准的 host=gateway�?
脚本预检查（针对常见 Python/Node shell 语法错误）仅检查有�?workdir 边界内的文件。如果脚本路径解析到 workdir 之外，则跳过该文件的预检查�?

配置

tools.exec.notifyOnExit（默认：true）：�?true 时，后台�?exec 会话在退出时加入系统事件队列并请求心跳�?
tools.exec.approvalRunningNoticeMs（默认：10000）：当带批准�?exec 运行超过此时间时发出单个”运行”通知�? 禁用）�?
tools.exec.host（默认：sandbox�?
tools.exec.security（默认：沙箱�?deny，gateway + node 未设置时�?allowlist�?
tools.exec.ask（默认：on-miss�?
tools.exec.node（默认：未设置）
tools.exec.pathPrepend：目录列表，�?exec 运行（gateway + 沙箱）时预先添加�?PATH�?
tools.exec.safeBins：仅 stdin 的安全二进制文件，无需显式白名单条目即可运行。行为详情见安全 bins�?
tools.exec.safeBinTrustedDirs：额外的显式目录，用�?safeBins 路径检查的受信任目录。PATH 条目永远不会被自动信任。内置默认值是 /bin �?/usr/bin�?
tools.exec.safeBinProfiles：每个安�?bin 的可选自定义 argv 策略（minPositional、maxPositional、allowedValueFlags、deniedFlags）�?

示例�?

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

PATH 处理

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 覆盖被发送到节点。env.PATH 覆盖被拒绝用于主机执行并被节点主机忽略。如果你在节点上需要额外的 PATH 条目，配置节点主机服务环境（systemd/launchd）或在标准位置安装工具�?

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

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

Control UI：节点标签页包含一个小�?Exec 节点绑定”面板，用于相同设置�?

会话覆盖（`/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 �?gateway 或节点主机上运行之前需要每请求批准�? 有关策略、白名单�?UI 流程，见 Exec 批准�?

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

白名�?+ 安全 bins

手动白名单执行仅匹配解析的二进制路径（无 basename 匹配）。当 security=allowlist 时，shell 命令仅在每个管道段都在白名单中或是安�?bin 时自动允许。链接（;、&&、||）和白名单模式下的重定向被拒绝，除非每个顶级段满足白名单（包括安�?bins）。重定向仍然不支持�?

autoAllowSkills �?exec 批准中的一条单独便利路径。它与手动路径白名单条目不同。对于严格的显式信任，保�?autoAllowSkills 禁用�?

将两个控件用于不同工作：

tools.exec.safeBins：小的仅 stdin 流过滤器�?
tools.exec.safeBinTrustedDirs：安�?bin 可执行文件路径的额外显式受信任目录�?
tools.exec.safeBinProfiles：自定义安全 bins 的显�?argv 策略�?
白名单：可执行文件路径的显式信任�?

不要�?safeBins 视为通用白名单，也不要添加解释器/运行时二进制文件（例�?python3、node、ruby、bash）。如果需要这些，使用显式白名单条目并保持批准提示启用�? openclaw security audit 在解释器/运行�?safeBins 条目缺少显式配置文件时发出警告，openclaw doctor --fix 可以脚手架缺失的自定�?safeBinProfiles 条目�?

完整策略详情和示例，�?Exec 批准 �?安全 bins 与白名单�?

示例

前台�?

{ "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, workspaceOnly: true, allowModels: ["gpt-5.2"] },
    },
  },
}