exec 是可变更的 shell 表面：只要所选主机或沙箱文件系统允许，命令就可以创建、编辑或删除文件。禁用 OpenClaw 文件系统工具（例如 write、edit 或 apply_patch）不会让 exec 变成只读。
通过 process 支持前台和后台执行。如果不允许使用 process，exec 会同步运行并忽略 yieldMs/background。后台会话按智能体划定范围；process 只能看到同一智能体的会话。
参数
要运行的 shell 命令。
命令的工作目录。
合并到继承环境之上的键/值环境覆盖项。
在此延迟后自动将命令转入后台（毫秒）。
立即将命令转入后台，而不是等待
yieldMs。覆盖此次调用配置的 exec 超时时间，单位为秒。适用于前台、后台、
yieldMs、Gateway 网关、沙箱和节点 system.run 执行。timeout: 0 会禁用该次调用的 exec 进程超时。可用时在伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
执行位置。
auto 在沙箱运行时处于活动状态时解析为 sandbox，否则解析为 gateway。普通工具调用会忽略此项。
gateway/node 安全由 tools.exec.security 和主机审批文件控制；只有在操作员明确授予提升访问权限时，提升权限模式才能强制使用 security=full。基线询问模式来自
tools.exec.ask 和主机审批。对于来自渠道的模型调用，当有效主机询问为 off 时，会忽略每次调用的 ask；否则它只能收紧为更严格的模式。使用显式 ask 值构造 exec 工具的受信任内部/API 调用方保持不变。当
host=node 时的节点 id/名称。请求提升权限模式：逃逸沙箱并进入配置的主机路径。只有当 elevated 解析为
full 时，才会强制使用 security=full。host只接受auto、sandbox、gateway或node。它不是主机名选择器；类似主机名的值会在命令运行前被拒绝。- 每次调用的
host=node可从auto使用；每次调用的host=gateway只在没有活动沙箱运行时时允许。 - 在没有额外配置时，
host=auto仍然“直接可用”：没有沙箱时解析为gateway；有活动沙箱时则保留在沙箱中。 elevated会逃逸沙箱并进入配置的主机路径：默认是gateway，或者当tools.exec.host=node（或会话默认值为host=node）时是node。仅当当前会话/提供商启用了提升权限访问时才可用。gateway/node审批由主机审批文件控制。node需要已配对的节点（配套应用或无头节点主机）。如果有多个节点可用，请设置exec.node或tools.exec.node来选择一个。exec host=node是节点的唯一 shell 执行路径；旧版nodes.run包装器已移除。- 在非 Windows 主机上，exec 会在设置了
SHELL时使用它；如果SHELL是fish，则优先使用PATH中的bash（或sh）以避免与 fish 不兼容的 bash 用法，然后在两者都不存在时回退到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 该快照。看起来像密钥的变量会被排除；沙箱和节点 exec 不使用此快照。在 Gateway 网关进程环境中设置OPENCLAW_EXEC_SHELL_SNAPSHOT=0可禁用此快照路径。 - 主机执行（
gateway/node）会拒绝env.PATH和加载器覆盖项（LD_*/DYLD_*），以防止二进制劫持或注入代码。 - OpenClaw 会在生成的命令环境中设置
OPENCLAW_SHELL=exec（包括 PTY 和沙箱执行），以便 shell/profile 规则可以检测 exec 工具上下文。 - 对于来自渠道的运行，当渠道提供了发送方/聊天身份 id 时，OpenClaw 还会在
OPENCLAW_CHANNEL_CONTEXT中公开一个窄范围的发送方/聊天身份 JSON 载荷。 exec不能运行openclaw channels login或/approveshell 命令：openclaw channels login是交互式渠道认证流程，而/approve需要通过审批命令处理器，不是 shell。在 Gateway 网关主机上的终端中运行渠道登录，或者在存在渠道专用登录智能体工具时使用它（例如whatsapp_login）。- 重要：沙箱隔离默认关闭。如果沙箱隔离关闭，隐式
host=auto会解析为gateway。显式host=sandbox仍会失败关闭，而不是静默地在 Gateway 网关主机上运行。启用沙箱隔离，或在带审批的情况下使用host=gateway。 - 脚本预检检查（用于常见 Python/Node shell 语法错误）只检查有效
workdir边界内的文件。如果脚本路径解析到workdir之外，则会跳过该文件的预检。当host=gateway且有效策略为security=full和ask=off时，预检也会完全跳过。 - 对于现在开始的长时间运行工作，只启动一次，并在启用自动完成唤醒且命令发出输出或失败时依赖它。使用
process查看日志、状态、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。 - 对于应在稍后或按计划发生的工作，请使用 cron，而不是
execsleep/delay 模式。
配置
| 键 | 默认值 | 说明 |
|---|---|---|
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 | |
tools.exec.mode | 未设置 | 规范化的策略旋钮。见下方模式。不能与 tools.exec.security/tools.exec.ask 组合使用。 |
tools.exec.node | 未设置 | |
tools.exec.notifyOnExit | true | 为 true 时，转入后台的 exec 会话会在退出时排入一个系统事件并请求一次 Heartbeat。 |
tools.exec.approvalRunningNoticeMs | 10000 | 当受审批控制的 exec 运行时间超过此值时，发出一次“运行中”通知（0 会禁用）。 |
tools.exec.strictInlineEval | false | 见内联 eval。 |
tools.exec.commandHighlighting | false | 为 true 时，审批提示可以在命令文本中高亮解析器派生的命令片段。可全局设置或按智能体设置；不会改变审批策略。 |
tools.exec.pathPrepend | 未设置 | 要前置到 exec 运行的 PATH 的目录列表（仅 Gateway 网关 + 沙箱）。 |
tools.exec.safeBins | 未设置 | 仅 stdin 的安全二进制文件，无需显式 allowlist 条目即可运行。见安全二进制文件。 |
tools.exec.safeBinTrustedDirs | /bin, /usr/bin | 用于 safeBins 路径检查的其他显式受信任目录。PATH 条目永远不会自动受信任。 |
tools.exec.safeBinProfiles | 未设置 | 每个安全二进制文件的可选自定义 argv 策略（minPositional、maxPositional、allowedValueFlags、deniedFlags）。 |
security=full、ask=off），这来自主机策略默认值，而不是来自 host=auto。如果你想要审批/allowlist 行为，请同时收紧 tools.exec.* 和主机审批文件；见 Exec 审批。要不管沙箱状态如何都强制 Gateway 网关或节点路由，请设置 tools.exec.host 或使用 /exec host=...。
示例：
模式
tools.exec.mode 是规范化的策略旋钮。设置它会派生 security/ask，并且不能与显式 tools.exec.security/tools.exec.ask 组合使用。
| 模式 | security | ask | 行为 |
|---|---|---|---|
deny | deny | off | Exec 被拒绝。 |
allowlist | allowlist | off | 只运行允许列表中的命令或 safe-bin 命令；不会询问其他内容。 |
ask | allowlist | on-miss | 匹配允许列表的命令会直接运行；其他所有内容都会询问人工。 |
auto | allowlist | on-miss | 匹配允许列表或 safe-bin 的命令会直接运行；其他所有内容会先经过 OpenClaw 原生自动审阅器，再询问人工。 |
full | full | off | 没有审批门禁。 |
ask/ask=always 仍然会每次都询问人工，无论模式如何。
内联 eval（strictInlineEval）
当 tools.exec.strictInlineEval 为 true 时，内联解释器 eval 形式需要审阅器或显式审批：python -c、node -e、ruby -e、perl -e、php -r、lua -e、osascript -e，以及其他受支持解释器和命令承载器中的类似形式（awk、find -exec、make、sed、xargs 等）。在 mode=auto 中，正常的 Exec 审批路径可能允许原生自动审阅器放行明确低风险的一次性命令；直接的 node-host system.run 调用仍然需要显式审批，因为它们无法把命令交给人工审批路径。如果审阅器要求，请求会转给人工。allow-always 仍可持久化良性的解释器/脚本调用，但内联 eval 形式不会变成持久允许规则。
PATH 处理
host=gateway：将你的登录 shellPATH合并到 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。
- macOS：
host=sandbox：在容器内运行sh -lc（登录 shell），因此/etc/profile可能会重置PATH。OpenClaw 会在 profile 来源加载后，通过内部环境变量前置env.PATH（无 shell 插值）；tools.exec.pathPrepend也适用于这里。host=node：只会把你传入的未被阻止的环境覆盖发送到节点。主机执行会拒绝env.PATH覆盖，节点主机会忽略它。如果你需要在节点上添加额外的 PATH 条目，请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
会话覆盖（/exec）
使用 /exec 为 host、security、ask 和 node 设置按会话默认值。发送不带参数的 /exec 可显示当前值。
示例：
/exec 仅对已授权发送者生效（渠道 allowlist/配对，加上 commands.useAccessGroups）。它只更新会话状态，不会写入配置。已授权的外部渠道发送者可以设置这些会话默认值。内部 gateway/webchat 客户端需要 operator.admin 才能持久化它们。
若要硬禁用 Exec，请通过工具策略拒绝它（tools.deny: ["exec"] 或按 Agent 设置）。除非你显式设置 security=full 和 ask=off，否则主机审批仍会适用。
Exec 审批（配套应用 / 节点主机）
沙箱隔离的智能体可以要求在exec 于 Gateway 网关或节点主机上运行前进行逐请求审批。请参阅 Exec 审批 了解策略、允许列表和 UI 流程。
需要审批时，Exec 工具会立即返回 status: "approval-pending" 和一个审批 id。一旦批准（或拒绝/超时），Gateway 网关仅针对已批准运行发出命令进度和完成系统事件（Exec running / Exec finished）。被拒绝或超时的审批是终态，不会用拒绝系统事件唤醒 Agent 会话。
在有原生审批卡片/按钮的渠道上，Agent 应优先依赖该原生 UI，只有在工具结果明确表示聊天审批不可用或手动审批是唯一路径时，才包含手动 /approve 命令。
允许列表 + safe bins
手动允许列表强制会匹配解析后的二进制路径 glob 和裸命令名 glob。裸名称只匹配通过 PATH 调用的命令，因此当命令为rg 时，rg 可以匹配 /opt/homebrew/bin/rg，但不能匹配 ./rg 或 /tmp/rg。
当 security=allowlist 时，只有在每个管道段都位于允许列表中或是 safe bin 时，shell 命令才会被自动允许。在 allowlist 模式下，除非每个顶层段都满足允许列表（包括 safe bins），否则链式命令（;、&&、||）和重定向会被拒绝。重定向仍不受支持。持久 allow-always 信任不会绕过该规则：链式命令仍要求每个顶层段都匹配。
autoAllowSkills 是 Exec 审批中的独立便捷路径，不等同于手动路径允许列表条目。若需要严格显式信任，请保持 autoAllowSkills 禁用。
这两个控件适用于不同用途：
tools.exec.safeBins：小型、仅 stdin 的流过滤器。tools.exec.safeBinTrustedDirs：safe-bin 可执行路径的显式额外受信目录。tools.exec.safeBinProfiles：自定义 safe bins 的显式 argv 策略。- 允许列表：对可执行路径的显式信任。
safeBins 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 python3、node、ruby、bash）。如果需要这些，请使用显式允许列表条目，并保持审批提示启用。
当解释器/运行时 safeBins 条目缺少显式 profile 时，openclaw security audit 会发出警告，openclaw doctor --fix 可以搭建缺失的自定义 safeBinProfiles 条目。当你显式将 jq 等宽行为 bin 加回 safeBins 时，openclaw security audit 和 openclaw doctor 也会发出警告（jq 支持广泛的程序和内置功能，因此优先使用显式允许列表条目或审批门禁运行）。如果你显式允许解释器，请启用 tools.exec.strictInlineEval，使内联代码 eval 形式仍然需要审阅器或显式审批。
有关完整策略详情和示例，请参阅 Exec 审批 和 Safe bins 与允许列表。
示例
前台：apply_patch
apply_patch 是 exec 的子工具，用于结构化多文件编辑。它默认启用，并可供任何模型提供商使用；allowModels 可以限制它。仅当你想禁用它或将其限制为特定模型时，才使用配置：
- 工具策略仍然适用；
allow: ["write"]会隐式允许apply_patch。 deny: ["write"]不会拒绝apply_patch；请显式拒绝apply_patch，或在补丁写入也应被阻止时使用deny: ["group:fs"]。- 配置位于
tools.exec.applyPatch下。 tools.exec.applyPatch.enabled默认为true；将其设为false可禁用该工具。tools.exec.applyPatch.workspaceOnly默认为true（限制在工作区内）。只有在你有意让apply_patch写入/删除工作区目录之外的内容时，才将其设为false。tools.exec.applyPatch.allowModels是模型 id 的可选允许列表（原始形式，如gpt-5.4，或完整形式，如openai/gpt-5.4）。设置后，只有匹配的模型会获得该工具；未设置时，所有模型都会获得它。