在工作区中运行 shell 命令。支持通过Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
process 进行前台 + 后台执行。
如果 process 被禁用，exec 会同步运行，并忽略 yieldMs/background。
后台会话按智能体划分范围；process 只能看到同一智能体的会话。
参数
要运行的 shell 命令。
命令的工作目录。
叠加到继承环境之上的键/值环境覆盖项。
经过此延迟（毫秒）后自动将命令转入后台。
立即将命令转入后台，而不是等待
yieldMs。覆盖此次调用配置的 exec 超时时间。只有在命令应在没有 exec 进程超时限制的情况下运行时，才设置
timeout: 0。可用时在伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
执行位置。
auto 会在沙箱运行时处于活动状态时解析为 sandbox，否则解析为 gateway。gateway / node 执行的强制执行模式。gateway / node 执行的审批提示行为。host=node 时的节点 ID/名称。请求提升模式 — 逃逸沙箱并进入配置的主机路径。只有在 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，而不是
execsleep/延迟模式。
配置
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 网关 + 节点的默认值。如果你想要审批/允许列表行为，请同时收紧
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 的安全二进制文件，可在没有显式允许列表条目的情况下运行。有关行为详情，请参阅安全二进制文件。tools.exec.safeBinTrustedDirs：用于safeBins路径检查的其他显式受信任目录。PATH条目永远不会自动受信任。内置默认值为/bin和/usr/bin。tools.exec.safeBinProfiles：每个安全二进制文件的可选自定义 argv 策略（minPositional、maxPositional、allowedValueFlags、deniedFlags）。
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
- macOS：
host=sandbox：在容器内运行sh -lc（登录 shell），因此/etc/profile可能会重置PATH。 OpenClaw 会在 profile sourcing 后通过内部环境变量预置env.PATH（无 shell 插值）；tools.exec.pathPrepend也适用于此处。host=node：只会把你传入的未被阻止的 env 覆盖项发送到节点。主机执行会拒绝env.PATH覆盖项，节点主机也会忽略它们。如果你需要在节点上添加额外的 PATH 条目， 请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
会话覆盖项（/exec）
使用 /exec 为 host、security、ask 和 node 设置按会话默认值。
发送不带参数的 /exec 可显示当前值。
示例：
授权模型
/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 通知。
在带有原生审批卡片/按钮的渠道上，智能体应优先依赖该
原生 UI，并且只在工具
结果明确表示聊天审批不可用或手动审批是唯一路径时，才包含手动 /approve 命令。
允许列表 + 安全二进制文件
手动允许列表强制执行会匹配解析后的二进制路径 glob 和裸命令名 glob。裸名称只匹配通过 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 策略。- 允许列表：对可执行路径的显式信任。
safeBins 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 python3、node、ruby、bash）。如果你需要这些，请使用显式允许列表条目，并保持审批提示启用。
当解释器/运行时 safeBins 条目缺少显式配置文件时，openclaw security audit 会发出警告，并且 openclaw doctor --fix 可以搭建缺失的自定义 safeBinProfiles 条目。
当你显式将 jq 等宽泛行为的二进制文件重新添加到 safeBins 时，openclaw security audit 和 openclaw doctor 也会发出警告。
如果你显式允许列出解释器，请启用 tools.exec.strictInlineEval，这样内联代码求值形式仍然需要新的审批。
有关完整策略细节和示例，请参阅 Exec 审批 和 安全二进制文件与允许列表。
示例
前台：apply_patch
apply_patch 是 exec 的子工具，用于结构化的多文件编辑。
它默认对 OpenAI 和 OpenAI Codex 模型启用。只有当你想禁用它或将它限制到特定模型时，才使用配置：
- 仅适用于 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。