Exec 工具

在工作区中运行 Shell 命令。exec 是一个可变的 Shell 表面：只要所选主机或沙箱文件系统允许，命令就可以在任何位置创建、编辑或删除文件。禁用 OpenClaw 文件系统工具（如 write、edit 或 apply_patch）并不会使 exec 变为只读。

通过 process 支持前台 + 后台执行。如果不允许 process，exec 将同步运行并忽略 yieldMs/background。 后台会话按代理（agent）限定范围；process 只能看到来自同一代理的会话。

参数

要运行的 Shell 命令。 命令的工作目录。 合并到继承环境之上的键/值环境覆盖项。 在此延迟（毫秒）后自动将命令置于后台。 立即将命令置于后台，而不是等待 `yieldMs`。 覆盖为此调用配置的 exec 超时时间。仅当命令应不受 exec 进程超时限制运行时，才设置 `timeout: 0`。 在可用时在伪终端中运行。用于仅限 TTY 的 CLI、编码代理和终端 UI。 在哪里执行。当沙盒运行时处于活动状态时，`auto` 解析为 `sandbox`，否则解析为 `gateway`。 对于普通工具调用会被忽略。`gateway` / `node` 安全性由 `tools.exec.security` 和 `~/.openclaw/exec-approvals.json` 控制；提升模式仅在操作员明确授予提升权限时才能强制执行 `security=full`。 `gateway` / `node` 执行的批准提示行为。 当 `host=node` 时的节点 ID/名称。 请求提升模式 — 逃逸沙箱进入配置的主机路径。仅当提升模式解析为 `full` 时，才会强制 `security=full`。

备注：

• host 默认为 auto：如果为会话启用了沙箱运行时，则为沙箱，否则为网关。
• host 仅接受 auto、sandbox、gateway 或 node。它不是一个主机名选择器；类似主机名的值会在命令运行之前被拒绝。
• auto 是默认路由策略，而非通配符。允许从 auto 进行每次调用的 host=node；仅当没有激活的沙箱运行时时，才允许每次调用的 host=gateway。
• tools.exec.mode 是规范化策略控制项。取值包括 deny、allowlist、ask、auto 和 full。autoOpenClaw 直接运行确定性允许列表/安全二进制匹配，并在询问人员之前，将其余每个 exec 批准案例通过 OpenClaw 的原生自动审核程序进行路由。ask / ask=always 每次仍需询问人员。
• 在没有额外配置的情况下，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、网关、沙箱和节点 system.runOpenClaw 执行。如果省略，OpenClaw 将使用 tools.exec.timeoutSec；显式的 timeout: 0 将禁用该调用的 exec 进程超时。
• 在非 Windows 主机上，如果设置了 SHELL，exec 将使用它；如果 SHELL 是 fish，它会优先使用 PATH 中的 bash（或 sh）以避免不兼容 fish 的脚本，如果两者都不存在，则回退到 SHELL。
• 在 Windows 主机上，exec 优先发现 PowerShell 7 (pwsh)（Program Files、ProgramW6432，然后是 PATH），然后回退到 Windows PowerShell 5.1。
• 在非 Windows Gateway 主机上，bash 和 zsh exec 命令使用启动快照。OpenClaw 从 shell 启动文件中捕获可 source 的别名/函数和一小组安全环境变量到 $OPENCLAW_STATE_DIR/cache/shell-snapshots/ 中，然后在每次 exec 命令之前 source 该快照。看似 Secret 的变量会被排除；沙箱和节点 exec 不使用此快照。在 Gateway 进程环境中设置 OPENCLAW_EXEC_SHELL_SNAPSHOT=0Gateway(网关) 可禁用此快照路径。
• 主机执行 (gateway/node) 会拒绝 env.PATH 和加载器覆盖 (LD_*/DYLD_*) 以防止二进制劫持或代码注入。
• OpenClaw 在生成的命令环境（包括 PTY 和沙箱执行）中设置 OPENCLAW_SHELL=exec，以便 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 会话会将系统事件加入队列，并在退出时请求一次心跳检测。
• tools.exec.approvalRunningNoticeMs (默认值: 10000): 当受审批限制的 exec 运行时间超过此值时，发出一次“正在运行”通知 (0 表示禁用)。
• tools.exec.timeoutSec (默认值: 1800): 每个命令的默认 exec 超时时间（以秒为单位）。单次调用的 timeout 会覆盖它；单次调用的 timeout: 0 会禁用 exec 进程超时。
• tools.exec.host (默认值: auto；当沙箱运行时处于活动状态时解析为 sandbox，否则为 gateway)
• tools.exec.security (默认值: 沙箱为 deny，未设置时网关 + 节点为 full)
• tools.exec.ask (默认值: off)
• 对于网关 + 节点，无审批主机 exec 是默认设置。如果您想要审批/允许列表行为，请同时收紧 tools.exec.* 和主机 ~/.openclaw/exec-approvals.json；请参阅 Exec approvals。
• YOLO 模式源自主机策略默认值 (security=full, ask=off)，而非 host=auto。如果您想强制使用网关或节点路由，请设置 tools.exec.host 或使用 /exec host=...。
• 在 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）需要审核者或显式批准。在 mode=auto 中，正常的 exec 批准路径可能会让原生自动审核者允许明显低风险的一次性命令；直接节点主机 system.run 调用仍需要显式批准，因为它们无法将命令交给人工批准路由。如果审核者提出请求，该请求将发送给人工。allow-always 仍可以持久化良性解释器/脚本调用，但内联求值形式不会成为持久化的允许规则。
• tools.exec.commandHighlighting (默认值: false): 为 true 时，批准提示可以在命令文本中突出显示解析器派生的命令范围。全局或按代理设置为 true，以便在不更改 exec 批准策略的情况下启用命令文本突出显示。
• tools.exec.pathPrepend: 要添加到 PATH 前面的目录列表，用于 exec 运行（仅限网关 + 沙盒）。
• 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
    • 为了防止用户 shell 配置（如 ~/.zshenv 或 /etc/zshenv）在启动期间覆盖优先路径，tools.exec.pathPrepend 条目会在执行前安全地添加到 shell 命令内的最终 PATH 前面。
• host=sandbox：在容器内运行 sh -lc（登录 shell），因此 /etc/profile 可能会重置 PATH。 OpenClaw 会在通过内部环境变量（无 shell 插值）获取 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 仅对 经过授权的发送方（渠道白名单/配对以及 commands.useAccessGroups）有效。 它仅更新 会话状态 而不写入配置。经过授权的外部渠道发送方可以 设置这些会话默认值。内部 Gateway(网关)/webchat 客户端需要 operator.admin 才能持久化它们。 要彻底禁用 exec，请通过工具策略（tools.deny: ["exec"] 或按代理）拒绝它。除非您显式设置 security=full 和 ask=off，否则主机批准 仍然适用。

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

沙箱隔离的代理可以在 exec 于 Gateway(网关) 或节点主机上运行之前要求每次请求都获得批准。 有关策略、白名单和 UI 流程，请参阅 Exec 批准。

当需要批准时，exec 工具会立即返回 status: "approval-pending"Gateway(网关) 和一个批准 ID。一旦获得批准（或被拒绝/超时）， Gateway(网关) 仅针对已批准的运行发出命令进度和完成系统事件 (Exec running / Exec finished)。被拒绝或超时的批准是终止性的，并且不会 用拒绝系统事件唤醒代理会话。 在具有原生批准卡片/按钮的渠道上，代理应首先依赖该 原生 UI，并且仅当工具结果 明确表明聊天批准不可用或手动批准是 唯一途径时，才包含手动 /approve 命令。

白名单 + 安全 bins

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

autoAllowSkills 是 exec 批准中一条单独的便捷路径。它与手动路径允许列表条目不同。为了严格实现显式信任，请保持 autoAllowSkills 禁用状态。

请使用这两个控制项来处理不同的任务：

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

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

有关完整的策略详情和示例，请参阅 Exec approvals 和 Safe bins versus allowlist。

示例

前台运行：

{ "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。

相关

• Exec Approvals — Shell 命令的批准门控
• 沙箱隔离 — 在沙箱隔离环境中运行命令
• Background Process — 长期运行的 exec 和进程工具
• Security — 工具策略和提升访问权限