本页介绍 OpenClaw exec 工具的完整参数和配置。exec 支持前台/后台执行、PTY 终端、沙箱/Gateway/节点多宿主环境。host 默认为 auto（有沙箱时用沙箱，否则用 gateway），gateway + node 的默认安全策略为 full（无审批提示）。

Exec 工具

在工作区运行 Shell 命令。通过 process 支持前台和后台执行。如果 process 被禁用，exec 将同步运行并忽略 yieldMs/background。后台会话按代理隔离，process 只能看到同一代理的会话。

参数

• command（必填）
• workdir（默认为 cwd）
• env（键值对覆盖）
• yieldMs（默认 10000）：超时后自动转后台
• background（布尔值）：立即转后台
• timeout（秒，默认 1800）：到期后终止进程
• pty（布尔值）：在可用时使用伪终端（TTY 专用 CLI、编码代理、终端 UI）
• host（auto | sandbox | gateway | node）：执行位置
• security（deny | allowlist | full）：gateway/node 的执行模式
• ask（off | on-miss | always）：gateway/node 的审批提示
• node（字符串）：host=node 时的节点 id/名称
• elevated（布尔值）：请求提权模式（逃出沙箱到配置的宿主机路径）；只有当 elevated 解析为 full 时才强制 security=full

注意事项：

• host 默认为 auto：会话有沙箱运行时时为沙箱，否则为 gateway。
• auto 是默认路由策略，不是通配符。从 auto 允许单次调用 host=node；只有当没有沙箱运行时处于活动状态时，才允许单次调用 host=gateway。
• 不做额外配置时，host=auto 可以直接"开箱即用"：没有沙箱时解析为 gateway；有活跃沙箱时保持在沙箱中。
• elevated 将沙箱逃逸到配置的宿主机路径：默认为 gateway，或当 tools.exec.host=node（或会话默认为 host=node）时为 node。只有当前会话/提供商启用了提升访问时才可用。
• gateway/node 的审批由 ~/.openclaw/exec-approvals.json 控制
• node 需要配对的节点（配套应用或无头节点主机）
• 如果存在多个节点，通过 exec.node 或 tools.exec.node 指定
• exec host=node 是节点的唯一 shell 执行路径；旧版 nodes.run 包装器已移除
• 在非 Windows 宿主机上，exec 使用 SHELL 环境变量；如果 SHELL 是 fish，优先从 PATH 中选 bash（或 sh）以避免 fish 不兼容脚本，若两者都不存在则回退到 SHELL
• 在 Windows 宿主机上，exec 优先发现 PowerShell 7（pwsh），回退到 Windows PowerShell 5.1
• 宿主执行（gateway/node）会拒绝 env.PATH 和加载器覆盖（LD_*/DYLD_*），防止二进制劫持或注入代码
• OpenClaw 在生成的命令环境中设置 OPENCLAW_SHELL=exec（含 PTY 和沙箱执行），方便 Shell 配置文件检测 exec 工具上下文
• 重要：沙箱默认关闭。若沙箱关闭，隐式 host=auto 解析为 gateway。显式 host=sandbox 仍然安全失败，而非静默在 Gateway 宿主机上运行。请启用沙箱或使用带审批的 host=gateway
• 脚本预检只检查有效 workdir 边界内的文件；若脚本路径解析到 workdir 外，该文件的预检将被跳过
• 对于立即开始的长时间运行任务，启动一次并依赖自动完成唤醒。使用 process 处理日志、状态、输入或干预；不要用 sleep 循环、超时循环或反复轮询来模拟调度
• 对于稍后或定期执行的任务，使用 cron 而不是 exec sleep/delay 模式

配置

• tools.exec.notifyOnExit（默认：true）：为 true 时，后台 exec 会话退出时推送系统事件并请求心跳
• tools.exec.approvalRunningNoticeMs（默认：10000）：当需要审批的 exec 运行超过此时长时，发出一次"运行中"通知（0 禁用）
• tools.exec.host（默认：auto；有沙箱运行时时解析为 sandbox，否则为 gateway）
• tools.exec.security（默认：沙箱为 deny，gateway + node 未设置时为 full）
• tools.exec.ask（默认：off）
• 无审批宿主机 exec 是 gateway + node 的默认行为。如果需要审批/allowlist 行为，同时收紧 tools.exec.* 和宿主机 ~/.openclaw/exec-approvals.json；参见 Exec 审批。
• security=full + ask=off 模式下，宿主机 exec 直接遵循配置的策略；没有额外的命令混淆预过滤器。
• tools.exec.node（默认：未设置）
• tools.exec.strictInlineEval（默认：false）：为 true 时，python -c、node -e、ruby -e、perl -e、php -r、lua -e、osascript -e 等内联解释器 eval 形式始终需要明确审批。allow-always 仍可持久化良性解释器/脚本调用，但内联 eval 形式每次仍会提示
• tools.exec.pathPrepend：要添加到 PATH 开头的目录列表（仅 gateway + 沙箱）
• tools.exec.safeBins：只读 stdin 的安全二进制文件，无需显式 allowlist 条目即可运行
• tools.exec.safeBinTrustedDirs：safe bins 路径检查的额外受信任目录。PATH 条目永远不会自动受信。内置默认为 /bin 和 /usr/bin
• tools.exec.safeBinProfiles：每个 safe 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 通过内部环境变量在 profile 加载后追加 env.PATH，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 node binding"面板。

会话覆盖（/exec）

使用 /exec 设置 host、security、ask 和 node 的每会话默认值。发送不带参数的 /exec 查看当前值。

示例：

/exec host=auto security=allowlist ask=on-miss node=mac-1

授权模型

/exec 只对授权发送者（渠道 allowlist/配对 + commands.useAccessGroups）生效。它只更新会话状态，不写入配置。若要彻底禁用 exec，通过工具策略拒绝（tools.deny: ["exec"] 或单代理配置）。除非显式设置 security=full 和 ask=off，宿主审批仍然生效。

Exec 审批（配套应用/节点宿主）

沙箱代理在 Gateway 或节点宿主上运行 exec 前，可能需要逐请求审批。详见 Exec 审批。

审批等待时，exec 工具立即返回 status: "approval-pending" 和审批 id。一旦审批（或拒绝/超时），Gateway 推送系统事件（Exec finished / Exec denied）。如果命令在 tools.exec.approvalRunningNoticeMs 后仍在运行，发出一次 Exec running 通知。

在有原生审批卡片/按钮的频道上，agent 应优先依赖该原生 UI，只有当工具结果明确表示聊天审批不可用或手动审批是唯一路径时才加入 /approve 命令。

Allowlist 与 safe bins

手动 allowlist 执行只匹配解析后的二进制路径（不匹配 basename）。security=allowlist 时，Shell 命令只有在每个管道段都在 allowlist 或 safe bins 中才会自动允许。链式命令（;、&&、||）和重定向在 allowlist 模式下被拒绝，除非每个顶层段都满足 allowlist（含 safe bins）。重定向仍然不支持。

持久 allow-always 信任不会绕过该规则：链式命令仍然需要每个顶层段匹配。

autoAllowSkills 是 exec 审批中的独立便利路径，与手动路径 allowlist 条目不同。若要严格的显式信任，保持 autoAllowSkills 禁用。

两个控制的用途：

• tools.exec.safeBins：小型、仅 stdin 的流过滤器
• tools.exec.safeBinTrustedDirs：safe bin 可执行路径的额外受信任目录
• tools.exec.safeBinProfiles：自定义 safe bin 的 argv 策略
• allowlist：对可执行路径的明确信任

不要将 safeBins 用作通用 allowlist，也不要添加解释器/运行时二进制文件（如 python3、node、ruby、bash）。如果需要，使用显式 allowlist 条目并保持审批提示启用。

openclaw security audit 会在解释器/运行时 safeBins 条目缺少显式配置文件时发出警告，openclaw doctor --fix 可以脚手架缺失的自定义 safeBinProfiles 条目。openclaw security audit 和 openclaw doctor 也会在你将 jq 等广义行为二进制文件显式添加到 safeBins 时发出警告。

如果你显式 allowlist 了解释器，启用 tools.exec.strictInlineEval，使内联代码 eval 形式仍然需要新的审批。

示例

前台执行：

{ "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 的子工具，用于结构化的多文件编辑。对 OpenAI 和 OpenAI Codex 模型默认启用。只有在需要禁用或限制特定模型时才使用配置：

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

注意事项：

• 仅适用于 OpenAI/OpenAI Codex 模型
• 工具策略仍然适用；allow: ["write"] 隐式允许 apply_patch
• 配置位于 tools.exec.applyPatch
• tools.exec.applyPatch.enabled 默认为 true；设为 false 可为 OpenAI 模型禁用该工具
• tools.exec.applyPatch.workspaceOnly 默认为 true（限制在工作区内）。只有在明确允许 apply_patch 写入/删除工作区目录以外时才设为 false

相关文档

• Exec 审批 — shell 命令的审批门
• 沙箱 — 在沙箱环境中运行命令
• 后台进程 — 长时间运行的 exec 和 process 工具
• 安全模型 — 工具策略和提升访问

常见问题

Q: host=auto 和 host=gateway 有什么区别？

A: host=auto 是动态的：有沙箱运行时时在沙箱中执行，否则在 gateway 上执行。host=gateway 是显式指定，无论是否有沙箱，始终在 gateway 宿主机上执行。另外，从 auto 模式发起单次调用 host=gateway 只有在没有活跃沙箱时才被允许，而 host=node 则无此限制。

Q: 沙箱关闭但我显式设置了 host=sandbox，exec 会怎么做？

A: 会安全失败（报错），不会静默回退到 gateway。这是 2026 年的新行为——之前版本会静默在 gateway 运行，现在改为快速失败以避免意外的宿主机执行。如需在无沙箱环境下运行，请使用 host=gateway（并配置适当的审批策略）。

Q: 如何永久设置 node 宿主机来运行 exec？

A: 使用 openclaw config set tools.exec.host node 将默认宿主机设为 node，然后通过 tools.exec.node 指定具体节点 id/名称。也可以用 /exec host=node node=<id> 临时覆盖当前会话，但不持久化。