内置工具

执行工具

在工作区中运行 shell 命令。通过 process 支持前台 + 后台执行。如果不允许使用 process，exec 会同步运行并忽略 yieldMs/background。后台会话按智能体限定范围；process 只能看到来自同一智能体的会话。

参数

commandstringrequired

要运行的 shell 命令。

workdirstring

命令的工作目录。

envobject

合并到继承环境之上的键/值环境覆盖项。

yieldMsnumber

在此延迟（毫秒）后自动将命令转入后台。

backgroundboolean

立即将命令转入后台，而不是等待 yieldMs。

timeoutnumber

覆盖此次调用配置的 exec 超时时间。仅当命令应在没有 exec 进程超时的情况下运行时，才设置 timeout: 0。

ptyboolean

在可用时在伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。

host'auto' | 'sandbox' | 'gateway' | 'node'

执行位置。当沙箱运行时处于活动状态时，auto 解析为 sandbox，否则解析为 gateway。

security'deny' | 'allowlist' | 'full'

gateway / node 执行的强制模式。

ask'off' | 'on-miss' | 'always'

gateway / node 执行的审批提示行为。

nodestring

当 host=node 时的节点 id/名称。

elevatedboolean

请求提权模式 —— 从沙箱逃逸到配置的主机路径。仅当 elevated 解析为 full 时，才会强制 security=full。

说明：

host 默认为 auto：当沙箱运行时对会话处于活动状态时使用沙箱，否则使用 Gateway 网关。
host 只接受 auto、sandbox、gateway 或 node。它不是主机名选择器；类似主机名的值会在命令运行前被拒绝。
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 包装器已移除。
timeout 适用于前台、后台、yieldMs、Gateway 网关、沙箱和节点 system.run 执行。如果省略，OpenClaw 使用 tools.exec.timeoutSec；显式 timeout: 0 会为该调用禁用 exec 进程超时。
在非 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 会在生成的命令环境中设置 OPENCLAW_SHELL=exec（包括 PTY 和沙箱执行），以便 shell/profile 规则可以检测 exec 工具上下文。
openclaw channels login 会被 exec 阻止，因为它是交互式渠道认证流程；请在 Gateway 网关主机上的终端中运行它，或者在存在渠道原生登录工具时从聊天中使用该工具。
重要：沙箱隔离默认关闭。如果沙箱隔离关闭，隐式 host=auto 会解析为 gateway。显式 host=sandbox 仍会封闭失败，而不是静默地在 Gateway 网关主机上运行。启用沙箱隔离，或在审批下使用 host=gateway。
脚本预检检查（针对常见 Python/Node shell 语法错误）只会检查有效 workdir 边界内的文件。如果脚本路径解析到 workdir 之外，则会跳过该文件的预检。
对于现在开始的长时间运行工作，启动一次，然后在启用自动完成唤醒且命令有输出或失败时依赖它。使用 process 查看日志、状态、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
对于应稍后发生或按计划发生的工作，请使用 cron，而不是 exec sleep/delay 模式。

配置

tools.exec.notifyOnExit（默认：true）：为 true 时，后台 exec 会话在退出时会排入一个系统事件并请求 Heartbeat。
tools.exec.approvalRunningNoticeMs（默认：10000）：当需要审批的 exec 运行时间超过此值时，发出一次“running”通知（0 表示禁用）。
tools.exec.timeoutSec（默认：1800）：每条命令的默认 exec 超时时间（秒）。逐次调用的 timeout 会覆盖它；逐次调用的 timeout: 0 会禁用 exec 进程超时。
tools.exec.host（默认：auto；当沙箱运行时处于活动状态时解析为 sandbox，否则解析为 gateway）
tools.exec.security（默认：沙箱为 deny，未设置时 Gateway 网关 + 节点为 full）
tools.exec.ask（默认：off）
无审批主机 exec 是 Gateway 网关 + 节点的默认行为。如果你想要审批/allowlist 行为，请同时收紧 tools.exec.* 和主机 ~/.openclaw/exec-approvals.json；参见 Exec 审批。
YOLO 来自主机策略默认值（security=full、ask=off），不是来自 host=auto。如果你想强制 Gateway 网关或节点路由，请设置 tools.exec.host 或使用 /exec host=...。
在 security=full 加 ask=off 模式下，主机 exec 会直接遵循配置的策略；没有额外的启发式命令混淆预过滤器或脚本预检拒绝层。
tools.exec.node（默认：未设置）
tools.exec.strictInlineEval（默认：false）：为 true 时，内联解释器 eval 形式（如 python -c、node -e、ruby -e、perl -e、php -r、lua -e 和 osascript -e）始终需要显式审批。allow-always 仍可持久化良性的解释器/脚本调用，但内联 eval 形式每次仍会提示。
tools.exec.pathPrepend：要前置到 exec 运行的 PATH 的目录列表（仅 Gateway 网关 + 沙箱）。
tools.exec.safeBins：仅 stdin 的安全二进制程序，可在没有显式 allowlist 条目的情况下运行。行为详情参见 Safe bins。
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 sourcing 之后通过内部环境变量前置 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 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 审批（配套应用 / 节点主机）

沙箱隔离的智能体可在 exec 于 Gateway 网关或节点主机上运行前要求逐请求审批。策略、allowlist 和 UI 流程见 Exec 审批。

当需要审批时，exec 工具会立即返回 status: "approval-pending" 和一个审批 id。获批后（或被拒绝 / 超时后）， Gateway 网关会发出系统事件（Exec finished / Exec denied）。如果命令在 tools.exec.approvalRunningNoticeMs 后仍在运行，会发出一次 Exec running 通知。在带有原生审批卡片/按钮的渠道上，智能体应优先依赖该原生 UI，并且仅当工具结果明确说明聊天审批不可用或手动审批是唯一路径时，才包含手动 /approve 命令。

Allowlist + 安全二进制程序

手动 allowlist 强制执行会匹配解析后的二进制路径 glob 和裸命令名 glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 rg 时，rg 可以匹配 /opt/homebrew/bin/rg，但不匹配 ./rg 或 /tmp/rg。当 security=allowlist 时，只有每个管道片段都在 allowlist 中或是安全二进制程序，shell 命令才会自动允许。链式执行（;、&&、||）和重定向在 allowlist 模式下会被拒绝，除非每个顶层片段都满足 allowlist（包括安全二进制程序）。重定向仍不受支持。持久的 allow-always 信任不会绕过该规则：链式命令仍要求每个顶层片段都匹配。

autoAllowSkills 是 exec 审批中的一个独立便利路径。它不同于手动路径 allowlist 条目。对于严格的显式信任，请保持禁用 autoAllowSkills。

对不同任务使用这两类控制项：

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

不要把 safeBins 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 python3、node、ruby、bash）。如果你需要这些，请使用显式允许列表条目，并保持启用审批提示。当解释器/运行时 safeBins 条目缺少显式配置文件时，openclaw security audit 会发出警告，而 openclaw doctor --fix 可以搭建缺失的自定义 safeBinProfiles 条目。当你显式地将 jq 等宽泛行为的二进制文件重新添加到 safeBins 中时，openclaw security audit 和 openclaw doctor 也会发出警告。如果你显式允许解释器，请启用 tools.exec.strictInlineEval，这样内联代码求值形式仍然需要新的审批。

有关完整策略详情和示例，请参阅 Exec 审批和安全二进制与允许列表。

示例

前台：

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

注意：

仅适用于 OpenAI/OpenAI Codex 模型。
工具策略仍然适用；allow: ["write"] 会隐式允许 apply_patch。
deny: ["write"] 不会拒绝 apply_patch；当补丁写入也应被阻止时，请显式拒绝 apply_patch，或使用 deny: ["group:fs"]。
配置位于 tools.exec.applyPatch 下。
tools.exec.applyPatch.enabled 默认为 true；将其设为 false 可为 OpenAI 模型禁用该工具。
tools.exec.applyPatch.workspaceOnly 默认为 true（限制在工作区内）。仅当你有意希望 apply_patch 在工作区目录之外写入/删除时，才将其设为 false。

执行工具

参数

配置

PATH 处理

会话覆盖（`/exec`）

授权模型

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

Allowlist + 安全二进制程序

示例

apply_patch

相关

Ask OpenClaw

# 参数

# 配置

# PATH 处理

# 会话覆盖（/exec）

# 授权模型

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

# Allowlist + 安全二进制程序

# 示例

# apply_patch

# 相关

参数

配置

PATH 处理

会话覆盖（`/exec`）

授权模型

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

Allowlist + 安全二进制程序

示例

apply_patch

相关