Exec 工具

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（布尔值）：请求提升模式（gateway 主机）；security=full 仅在 elevated 解析为 full 时强制执行

注意事项：

• host 默认为 sandbox。
• 当沙箱关闭时，elevated 被忽略（exec 已经在主机上运行）。
• gateway/node 审批由 ~/.openclaw/exec-approvals.json 控制。
• node 需要已配对的节点（伴侣应用或无头节点主机）。
• 如果有多个节点可用，设置 exec.node 或 tools.exec.node 来选择一个。
• 在非 Windows 主机上，exec 在设置了 SHELL 时使用该 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 在生成的命令环境中设置 OPENCLAW_SHELL=exec（包括 PTY 和沙箱执行），以便 shell/profile 规则可以检测 exec 工具上下文。
• 重要提示：沙箱默认关闭。如果沙箱关闭且明确配置/请求了 host=sandbox，exec 现在会安全失败（fail closed）而不是静默地在 gateway 主机上运行。请启用沙箱或使用带审批的 host=gateway。
• 脚本预检查（针对常见的 Python/Node shell 语法错误）仅检查有效 workdir 边界内的文件。如果脚本路径解析到 workdir 之外，该文件的预检查将被跳过。

配置

• tools.exec.notifyOnExit（默认：true）：为 true 时，后台化的 exec 会话在退出时入队系统事件并请求心跳。
• tools.exec.approvalRunningNoticeMs（默认：10000）：当需要审批的 exec 运行超过此时间时，发出一次"running"通知（0 禁用）。
• tools.exec.host（默认：sandbox）
• tools.exec.security（默认：沙箱为 deny，未设置时 gateway + node 为 allowlist）
• tools.exec.ask（默认：on-miss）
• tools.exec.node（默认：未设置）
• tools.exec.pathPrepend：在 exec 运行时前置到 PATH 的目录列表（仅限 gateway + sandbox）。
• 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.PATH 覆盖，节点主机也会忽略。如果你需要在节点上添加额外的 PATH 条目，请配置节点主机服务环境（systemd/launchd）或将工具安装在标准位置。

每个智能体的节点绑定（在配置中使用智能体列表索引）：

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

控制 UI：Nodes 标签页包含一个小型"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 或节点主机之前要求逐请求审批。参见 Exec 审批 了解策略、允许列表和 UI 流程。当需要审批时，exec 工具立即返回 status: "approval-pending" 和审批 ID。一旦批准（或拒绝/超时），Gateway 发出系统事件（Exec finished / Exec denied）。如果命令在超过 tools.exec.approvalRunningNoticeMs 后仍在运行，会发出一条 Exec running 通知。

允许列表 + 安全二进制文件

手动允许列表执行仅匹配解析后的二进制路径（不匹配基本名称）。当 security=allowlist 时，shell 命令仅在每个管道段都被允许列表或安全二进制文件匹配时才自动允许。在允许列表模式下，链式操作（;、&&、||）和重定向会被拒绝，除非每个顶层段都满足允许列表（包括安全二进制文件）。重定向不受支持。autoAllowSkills 是 exec 审批中的一个独立便捷路径，与手动路径允许列表条目不同。如果需要严格的显式信任，请保持 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 条目生成脚手架。有关完整的策略详情和示例，请参见 Exec 审批 和 安全二进制文件与允许列表对比。

示例

前台执行：

{ "tool": "exec", "command": "ls -la" }

后台执行 + 轮询：

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":""}

发送按键（tmux 风格）：

{"tool":"process","action":"send-keys","sessionId":"","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"","keys":["Up","Up","Enter"]}

提交（仅发送回车）：

{ "tool": "process", "action": "submit", "sessionId": "" }

粘贴（默认使用括号粘贴模式）：

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

apply_patch（实验性）

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

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

注意事项：

• 仅适用于 OpenAI/OpenAI Codex 模型。
• 工具策略仍然适用；allow: ["exec"] 隐式允许 apply_patch。
• 配置位于 tools.exec.applyPatch 下。
• tools.exec.applyPatch.workspaceOnly 默认为 true（限于工作区内）。仅当你确实需要 apply_patch 在工作区目录之外写入/删除时，才将其设置为 false。