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（布尔值）：请求提权模式（网关主机）；只有提权解析为 full 时才强制 security=full

注意事项：

host 默认为 sandbox。
沙箱关闭时 elevated 被忽略（执行已经在主机上运行了）。
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_*）以防止二进制劫持或注入代码。
OpenClaw 在生成的命令环境中（包括 PTY 和沙箱执行）设置 OPENCLAW_SHELL=exec，让 shell/profile 规则能检测到 exec 工具上下文。
重要：沙箱默认关闭。如果沙箱关闭且显式配置/请求了 host=sandbox，exec 现在会失败关闭而不是静默在网关主机上运行。启用沙箱或使用 host=gateway 加审批。
脚本预检查（针对常见的 Python/Node shell 语法错误）只检查生效 workdir 边界内的文件。如果脚本路径解析到 workdir 之外，该文件跳过预检查。

配置

tools.exec.notifyOnExit（默认：true）：为 true 时，后台 exec 会话退出时入队系统事件并请求心跳。
tools.exec.approvalRunningNoticeMs（默认：10000）：当审批门控的 exec 运行超过该时间时发出一次”运行中”通知（0 禁用）。
tools.exec.host（默认：sandbox）
tools.exec.security（默认：沙箱为 deny，网关 + 节点未设置时为 allowlist）
tools.exec.ask（默认：on-miss）
tools.exec.node（默认：未设置）
tools.exec.pathPrepend：exec 运行时追加到 PATH 前面的目录列表（仅网关 + 沙箱）。
tools.exec.safeBins：仅 stdin 的安全二进制，无需显式允许列表条目即可运行。行为详情参见安全二进制。
tools.exec.safeBinTrustedDirs：safeBins 路径检查的额外显式受信目录。PATH 条目永远不会被自动信任。内置默认值是 /bin 和 /usr/bin。
tools.exec.safeBinProfiles：可选的每安全二进制自定义 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 在 profile 加载后通过内部环境变量追加 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"

控制界面：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 在网关或节点主机上运行前可以要求按请求审批。参见执行审批了解策略、允许列表和 UI 流程。

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

允许列表 + 安全二进制

手动允许列表强制匹配的是解析后的二进制路径（不做基础名匹配）。security=allowlist 时，shell 命令只在管道每个段都在允许列表或安全二进制中时才自动允许。链接（;、&&、||）和重定向在允许列表模式下被拒绝，除非每个顶层段都满足允许列表（包括安全二进制）。重定向不受支持。

autoAllowSkills 是执行审批中的一个单独便捷路径。它和手动路径允许列表条目不同。要严格显式信任，保持 autoAllowSkills 禁用。

两个控制用于不同的目的：

tools.exec.safeBins：小的、仅 stdin 流过滤器。
tools.exec.safeBinTrustedDirs：安全二进制可执行路径的额外显式受信目录。
tools.exec.safeBinProfiles：自定义安全二进制的显式 argv 策略。
允许列表：对可执行路径的显式信任。

不要把 safeBins 当作通用允许列表用，也不要添加解释器/运行时二进制（比如 python3、node、ruby、bash）。如果需要那些，使用显式允许列表条目并保持审批提示启用。openclaw security audit 在解释器/运行时 safeBins 条目缺少显式配置时会发出警告，openclaw doctor --fix 可以为缺失的自定义 safeBinProfiles 条目生成骨架。

完整的策略细节和示例，参见执行审批和安全二进制 vs 允许列表。

示例

前台：

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