Exec 工具

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

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

已完成的调用直接返回命令输出。仅当 exec 报告命令仍在运行并提供 sessionId 时才使用 process；命令打印的标识符属于普通输出，不是进程句柄。

参数¶

command string（路径）必填

要运行的 shell 命令。

workdir string（路径）默认值：cwd

命令的工作目录。对于本地执行，相对路径相对于会话的默认 cwd 解析；. 保留该目录。路径按字面处理，因此 ~ 不会被展开。

env object（路径）

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

yieldMs number（路径）默认值：10000

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

background boolean（路径）默认值：false

立即将命令转入后台，而不是等待 yieldMs。工具返回后进程超时仍然适用。

timeoutSeconds number（路径）默认值：tools.exec.timeoutSeconds

以秒为单位限制命令的总生存时间，覆盖本次调用的已配置 exec 超时。即使在 background 或 yieldMs 返回会话 ID 之后，超时到期也会终止进程。yieldMs 控制工具在转入后台前等待的时间。process 工具的 timeout 控制一次轮询等待的时间，同样以毫秒为单位。

适用于 gateway、sandbox 和 node 的 system.run 执行。timeoutSeconds: 0 会禁用该次调用的 exec 进程超时。对于 gateway 或 sandbox 中的持久服务，请使用 background: true 配合 timeoutSeconds: 0，完成后使用 process 的 kill 操作停止它。禁用此超时并不会让进程在主机或 worker 关闭后继续存活。

Codex 前台 node_exec 继承此预算（包括按 agent 的默认值），而不是普通的动态工具超时。即使命令计时器被禁用，Node 传输等待仍然有界；Stop 和回合取消仍然适用。参见 Codex 超时。

pty boolean（路径）默认值：false

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

host 'auto' | 'sandbox' | 'gateway' | 'node'（路径）默认值：auto

执行位置。省略 host 或使用 auto 可继承已配置的 exec 主机，包括 agent 和会话的覆盖项。当该配置的主机也是 auto 时，如果沙箱运行时处于活动状态则解析为 sandbox，否则解析为 gateway。需要沙箱的会话无论配置的主机是什么都会保持沙箱化。

ask 'off' | 'on-miss' | 'always'（路径）

基线询问模式由 tools.exec.mode 和主机审批决定。对于来自渠道的模型调用，当有效的主机 ask 为 off 时，单次调用的 ask 会被忽略。否则它只能强化为更严格模式。

node string（路径）

当 host=node 时的 node id/name。

elevated boolean（路径）默认值：false

请求提升模式：当操作者允许时，从沙箱逃逸到配置的主机路径。只有当前有效的安全策略和 ask 策略已经允许 full 和 off 时，提升的 full 才会跳过审批。

注意：

• host 只接受 auto、sandbox、gateway 或 node。它不是主机名选择器。类似主机名的值会在命令运行前被拒绝。
• 仅当没有沙箱运行时处于活动状态时，才允许从 auto 进行单次调用的 host=node 和 host=gateway。当沙箱运行时处于活动状态时，auto 会将 exec 保留在沙箱中，并拒绝这两个覆盖项。请显式设置 tools.exec.host=node（或 gateway）以在那里运行。
• 在没有额外配置的情况下，host=auto 仍然“开箱即用”：没有沙箱时它会解析为 gateway。存在活跃沙箱时它会留在沙箱中。
• elevated 从沙箱逃逸到配置的主机路径：默认为 gateway，当 tools.exec.host=node（或会话默认值为 host=node）时为 node。仅当当前会话/provider 启用了提升访问权限时才可用。
• gateway/node 的审批由主机审批文件控制。
• node 需要一个已配对且已连接的、支持 system.run 的节点（配套应用或无头 node 主机）。未设置目标时，exec 会选择唯一的合格节点。如果连接了多个合格节点，请设置 exec.node、tools.exec.node 或 /exec node=... 来选择其中一个。它从不使用活动的 Canvas 目标。显式或绑定的目标本身必须已连接且可执行。完成的结果会在命令输出旁标识所选的节点。
• exec host=node 是节点唯一的 shell 执行路径。旧版 nodes.run 包装器已于 2026.3.31 移除。
• 在非 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 将可 source 的别名/函数和一小部分安全环境变量从 shell 启动文件捕获到 $OPENCLAW_STATE_DIR/cache/shell-snapshots/，然后在每条 exec 命令之前 source 该快照。看起来像秘密的变量会被排除。Sandbox 和 node 的 exec 不使用此快照。在 Gateway 进程环境中设置 OPENCLAW_EXEC_SHELL_SNAPSHOT=0 可禁用此快照路径。
• 主机执行（gateway/node）拒绝 env.PATH 和加载器覆盖项（LD_*/DYLD_*），以防止二进制劫持或注入代码。
• 精确的 "cat" 或空的 GIT_PAGER 和 PAGER 覆盖项会被规范化为空值，包括在 node shell 包装器执行中。这可以在不通过 PATH 传递可执行分页器名称的情况下禁用 Git 分页。其他程序可能会以不同方式解释空的 PAGER。需要时请使用它们的非交互标志。其他分页器命令、路径、空白变体和 MANPAGER 覆盖项仍会被阻止。
• OpenClaw 在生成的命令环境中设置 OPENCLAW_SHELL=exec（包括 PTY 和沙箱执行），以便 shell/profile 规则可以检测到 exec 工具的上下文。
• 使用默认关闭的秘密出口代理时，Gateway 托管的 exec 只会以进程本地哨兵的形式接收共享存储中的 secret 条目。经过认证的回环代理会在出站 HTTPS 请求时替换为明文。每个受管进程都有自己的代理授权，该授权在发起回合期间持续有效，并在进程退出、取消、超时或 Gateway 关闭时被撤销。
• 共享存储中的 env 条目有意使用明文，并从下一次 agent 运行开始到达 Gateway 托管的 exec。它们不会到达沙箱、远程 node、ACP 或 Codex 原生 shell 执行。在 Codex harness 下，请使用 gateway_exec 作为此 OpenClaw 管理的环境路径。
• 使用受管的 GitHub 身份时，Gateway 托管的 exec 会验证所选配置文件，并在每次进程启动时私下绑定其凭据。不可用的配置文件会以重新连接指引阻止该本地执行，而不会回退到原生 keyring 凭据。正在运行的 shell 会保留其启动令牌。后续的 exec 启动会观察到刷新。Codex 原生 shell 不共享此启动绑定。
• 秘密出口设置 NODE_USE_ENV_PROXY=1，以便受支持的 Node.js 全局 fetch 客户端遵循进程作用域的代理。它不使用 NODE_OPTIONS。
• 对于来自渠道的运行，当渠道提供了这些 id 时，OpenClaw 还会在 OPENCLAW_CHANNEL_CONTEXT 中暴露一个精简的发送者/聊天身份 JSON 负载。
• exec 无法运行 openclaw channels login 或 /approve shell 命令：openclaw channels login 是一个交互式渠道认证流程，而 /approve 需要通过审批命令处理器而非 shell 执行。请在 gateway 主机的终端中运行渠道登录，或使用渠道专属的登录 agent 工具（例如 whatsapp_login）。
• 重要提示：沙箱化在默认情况下处于关闭状态。如果沙箱化关闭，隐式的 host=auto 会解析为 gateway。显式的 host=sandbox 仍然会失败关闭，而不是静默地在 gateway 主机上运行。请启用沙箱化或使用带审批的 host=gateway。
• Python 脚本的预检只检查有效 workdir 边界内的文件是否存在常见 shell 语法错误。如果脚本路径解析到 workdir 之外，文件检查会被跳过。JavaScript 源码交由 Node 处理，Node 会返回其正常的诊断信息和退出码；运行时错误之前的语句可能已经执行。对歧义 Python/Node 解释器命令的单独限制仍然适用。当 host=gateway 且有效策略为 security=full 且 ask=off 时，预检会完全跳过。
• 对于现在开始的长时间运行工作，请启动一次，并在启用了自动完成唤醒且命令产生输出或失败时依赖该唤醒。对于日志、状态、输入或干预，请使用 process。不要用 sleep 循环、超时循环或重复轮询来模拟调度。
• 当 tools.exec.notifyOnExit=false 时，运行中结果会在其文本和结构化 followUp 中明确说明自动完成唤醒已被禁用。如果任务需要结果，请在结束回合前使用 process poll 和超时来收集结果，除非已经安排了其他延续。正在运行的进程或活动中的会话目标并不会安排该延续。
• 当已批准的异步命令完成时，其延续使用 agents.defaults.timeoutSeconds 中的常规 agent 运行超时。后续观察者可以在已接受的 agent 运行继续时完成等待。
• 子 agent 会话不会收到自动的后台 exec 唤醒。在没有其他完成来源的情况下让出控制权之前，请使用 process poll 收集结果。
• 进程所有者跟踪 agent 启动的后台命令。使用返回的进程会话 ID 来检查输出、轮询或停止命令；其完成可以唤醒 agent。
• 对于应该在稍后或按计划执行的工作，请使用 cron，而不是 exec 的 sleep/延迟模式。

配置¶

对于 gateway 和 node，无需审批的 host exec 是默认行为（mode=full）——这来自 host 策略默认值，而不是来自 host=auto。如果你希望使用审批/allowlist 行为，请设置 tools.exec.mode 并收紧 host 审批文件。见 Exec 审批。若要强制使用 gateway 或 node 路由，无论沙箱状态如何，请设置 tools.exec.host 或使用 /exec host=...。

示例：

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

模式¶

tools.exec.mode 是规范持久化策略控制项。运行时安全和审批行为由它派生。

在消息中使用 /exec ask=always 可要求该次运行进行人工审批。它不会持久化到后续消息。对于会话级策略，请使用 会话权限模式。

自动审查审批是一次性的。reviewer 会返回 allow、deny 或 ask：allow 仅运行一次低风险或中风险命令。deny 会向 agent 返回原因，agent 必须选择实质更安全的替代方案或询问用户，而不是绕过拒绝。ask 请求人工审批。包含 reviewer 指示文本的命令会被拒绝并返回给 agent，以便其重写命令。它们不会直接升级到人工审批。reviewer 失败、超时和无效响应也会询问人工。在 gateway 上，同一会话中连续三次 reviewer 拒绝会将第三条命令升级到人工审批。reviewer 允许或已解决的人工审批会重置计数。

Set tools.exec.reviewer.thinking 为 minimal、low、medium、high、xhigh 或 max，以独立于主代理选择审查器推理努力。例如，reviewer: { model: "openai/gpt-5.6-terra", thinking: "low" } 请求低努力审查。支持的级别会根据所选模型进行规范化。省略 thinking 以保留现有提供商默认值；审查器不会继承主代理的 thinking 设置。相同设置也可在 agents.entries.<id>.tools.exec.reviewer 下使用。它也适用于基于模型的小部件审查，但不会配置 Codex 的原生 Guardian 审查器。

Set tools.exec.reviewer.fastMode 为 true，以在受支持的 OpenAI Responses 和 ChatGPT/OAuth 路由上请求 Fast 处理，或设为 false 表示标准处理。例如，reviewer: { model: "openai/gpt-5.6-terra", thinking: "low", fastMode: true } 同时请求低推理努力和优先处理。省略 fastMode 以保留提供商默认值。此设置独立于主代理的 Fast 模式，也可按代理使用。优先处理可能成本更高，并仍受提供商/模型可用性限制；其他提供商可能忽略此设置。

模型准备和完成各自获得配置的 tools.exec.reviewer.timeoutMs 预算。超时会立即返回人工审批。待处理的准备和提供商清理保持归属，直到它们结束。在其超时后完成的准备不会启动审查。

对于嵌入式代理运行，审查器会收到当前对话的有界且已脱敏的摘录：用户请求、助手文本、工具调用和工具结果，并按来源标注。它使用此上下文判断命令是否服务于用户请求。该摘录是不可信的证据，而不是指令。对于直接节点 system.run 调用和小部件，对话上下文不可用。

在网关上，命令在审查前仍必须通过现有的可变文件绑定检查。这些检查继续拒绝 heredoc、未解析的可执行文件和缺失的脚本操作数。整个普通外部分发链——每个原始包装器可执行文件和最终命令段可执行文件——在审查时绑定，并在启动前重新检查：受保护可执行文件仅使用已解析的真实路径身份，而可写可执行文件还使用内容哈希。可执行文件解析发生变化（包括 PATH 中更早出现的新可执行文件）会拒绝已批准的运行。已提交的主机审批策略也会在最终进程派生边界重新验证，包括在异步启动工作之后和 PTY 回退之前。策略撤销会阻止待启动的进程；它不会停止已经启动的进程。仅身份绑定不会使其他符合条件的人工审批变为一次性。

审查器批准的未固定执行要求完整分发链进行身份绑定：授权计划必须完整、使用直接传输，并为每个包装器和最终可执行文件记录可执行文件操作数。符合条件的通配符和链保留其参数展开，同时每个包装器和可执行文件都固定到其绑定的绝对调用路径。可执行文件符号链接保留其调用语义（包括 Python 虚拟环境），同时其规范目标和可变内容仍保持绑定并重新验证。从授权计划重建的命令使用准备好的运行时环境，而不加载 shell 启动快照，因此别名、函数和启动 PATH 变更无法替换已批准的分发。普通完整模式命令保留 shell 启动自定义。节点主机自动审查接受准备好的固定直接命令，包括节点自身的规范 POSIX shell 传输，围绕一个带静态参数的直接绝对可执行文件。当网关无法检查节点的内存绑定时，裸可执行文件名、未加引号的通配符和用户提供的包装器仍需要人工审批。节点可执行文件身份重新验证覆盖从本地策略评估到分发的过程。节点主机启动还会在异步准备后重新验证已提交的审批策略。它不会在远程人工审批等待期间保留每个内部 shell 可执行文件的身份。有关该边界，请参阅 解释器/运行时命令。

Shell -c 包装器、带赋值的 env、xcrun、BusyBox/Toybox 小程序、shell builtin/command/exec 分发以及任何其他不完整分发链都会跳过审查器，并返回 Exec auto-review skipped: dispatch chain cannot be bound。在自动模式下，当现有绑定检查成功时，这些形式采用一次性人工审批路径。现有绑定拒绝仍然适用。普通命令和透明 env（无赋值）在其完整链被绑定时仍符合条件。没有持久化数据模型变更：绑定在审批生命周期内保留在内存中。

请求命令中的 POSIX 登录或交互式 shell 包装器从不接受自动审查。当绑定成功时（例如 bash -lc 'printf ok'），它们需要人工审批，因为其隐式启动文件位于操作数绑定之外。现有绑定拒绝仍优先。作为代码加载选项被拒绝的交互式形式仍被拒绝。这适用于请求命令中的包装器。网关的普通 shell 启动快照保持不变。

显式 ask=always、安全审计抑制变更以及超过审查候选上限的命令直接转到人工审批。

尚未由显式运行时或原生策略决定的 Codex app-server 命令审批使用人工审批路径。OpenClaw 不会为这些请求运行其配置的 exec 审查器，因为 Codex 未公开可强制执行的已解析可执行文件，无法将审查决定绑定到 Codex 运行的命令。

内联求值（strictInlineEval）¶

tools.exec.strictInlineEval 是单独的选择加入设置，默认值为 false。当普通主机审批评估运行时，启用它要求对已识别的内联解释器求值形式进行审查器或显式审批，即使 exec 和主机策略允许 full/off。示例包括 python -c、node -e、ruby -e、perl -e、php -r、lua -e、osascript -e，以及其他受支持解释器和命令载体（awk、find -exec、make、sed、xargs 等）中的类似形式。在 mode=auto 中，普通 exec 审批路径可能允许原生自动审查器批准低风险或中风险的一次性命令。直接节点主机 system.run 调用仍需要显式审批，因为它们无法将命令交给人工审批路径。审查器拒绝会附带原因返回给代理。ask 转到人工。allow-always 仍可以持久化良性解释器/脚本调用，但内联求值形式不会成为持久允许规则。

仅配置 tools.exec.mode: "full" 不会跳过此检查。Gateway 执行在以下任一情况下会跳过主机审批路径：

• 完全权限会话保持有效 security 为 full，ask 为 off。
• 允许 elevated-full 执行，并且 exec 策略和主机审批都允许 full/off。

这些路径会跳过检测严格内联求值的审批所有者。收紧完全会话的 ask 模式会恢复该求值，即使会话仍然绕过主机审批文件下限。参见 会话权限模式 和 提升模式。

对于这些形式下普通配置的 full/off 执行且无需提示，请保持 strictInlineEval 未设置或将其设置为 false。当检测运行时，askFallback: "full" 不满足严格内联求值审批。

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 通过内部环境变量在 profile 加载后前置 env.PATH（不进行 shell 插值）。tools.exec.pathPrepend 在此也适用。
• 受控的本地 stdio 进程上的原生 Codex 会收到非空配置前缀和 Gateway CLI shim，并将其置于显式配置的原生 shell PATH 之前；如果未设置原生值，则使用 Gateway 进程的 PATH。请求级原生 PATH 覆盖优先于原生配置文件；显式空 PATH 仅保留前缀。每个 agent 的 tools.exec.pathPrepend 会覆盖全局列表，包括空列表。OpenClaw 会将此环境应用于新建和恢复的原生线程，而不改变原生登录 shell 策略。Codex 在加载 shell 快照后重新应用环境，但当快照不可用或被绕过，或命令 shell 启动时，shell 启动文件仍可能替换 PATH。Codex 现有的 allow_login_shell = false 设置可选择退出登录 profile 启动；它不会抑制所有 shell 启动文件。主机 PATH 条目不会转发到 sandbox、remote-workspace 或基于 socket 的 Codex 执行。
• host=node：仅将你传递的未被阻止的 env 覆盖发送到 node。对于主机执行，env.PATH 覆盖会被拒绝，并被 node 主机忽略。如果需要在 node 上添加额外 PATH 条目，请配置 node 主机服务环境（systemd/launchd）或将工具安装到标准位置。

每个 agent 的 node 绑定（在配置中使用带键的 agent ID）：

openclaw config get agents.entries
openclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"

控制 UI：设备 页面包含一个小型“执行节点绑定”面板，用于相同设置。已保存的目标可能变得无法解析或停止广播执行支持。其绑定仍保持选中，并标记为 不可用。即使没有具备执行能力的 node，你也可以使用 任意 node 或 使用默认 清除它。受支持的名字、地址和 ID 前缀可在不重写已保存引用的情况下解析。

Python 环境（uv）¶

在 uv 管理的项目 中，单独的 python 或 python3 会使用 exec 主机 PATH 选择的解释器。如果项目环境不在该路径上，导入安装在该环境中的依赖项可能会以 ModuleNotFoundError 失败。

将 workdir 设置为项目目录，并运行 uv run python3 script.py 以使用其环境。当项目环境已在 PATH 上时，单独的解释器也可用。

对于重复的 agent 工作，请将项目约定记录在工作区的 AGENTS.md 中，例如：

- Run Python scripts from this project with `uv run python3 script.py` so they use its dependencies.

会话覆盖（/exec）¶

单独发送 /exec host=... node=... 以设置 每会话 放置默认值。security 和 ask 仅适用于 当前消息。在要运行的任务中包含它们。不带参数发送 /exec 以显示已解析的默认值。

示例：

/exec host=node node=worker-1
/exec security=allowlist ask=always inspect the build output

/exec 仅通过 channel 允许列表/配对和访问组对 授权发送者 生效。访问组强制始终开启。它不会写入配置。授权的外部 channel 发送者可以持久化放置默认值。内部 gateway/webchat 客户端需要 operator.admin 才能执行此操作。轮次范围的 security 和 ask 不需要该持久化权限。

单独的 /exec security=deny 会确认仅运行设置，但不会启动 agent 运行，也不影响下一条消息。使用 会话权限模式 以在消息之间保持策略。

sessions.patch 和 sessions.patchMany 中的 execSecurity 和 execAsk 字段已在 2026.8.1 中退役。它们仍保留在 protocol v4 wire schema 中，但包含任一字段（包括 null）的请求会被拒绝，并返回 INVALID_REQUEST 和替换指导。设置 permissionMode（read-only、guarded、workspace 或 full）以定义会话范围策略，或在消息中使用 /exec 进行单次运行。

当会话具有权限模式时，每轮 /exec 覆盖只能收紧其 security 和审批策略。例如，/exec security=deny 即使在全访问会话中也会阻止该轮的 exec。请求更宽松 security 或更少审批的覆盖不会改变会话模式的限制。全访问会话仅在有效 security 保持为 full 时绕过主机审批文件下限。仅收紧 ask 仍会应用请求的审批级别，而不会恢复这些下限。

To hard-disable exec, deny it via tool policy (tools.deny: ["exec"] or per-agent). Outside the full-access session exception above, host approval-file floors still apply.

Exec 审批（companion app / node 主机）¶

沙箱代理可以在 exec 在 gateway 或 node 主机上运行之前，要求逐次请求审批。有关策略、允许列表和 UI 流程，请参阅 Exec 审批。

当可以送达人工审批时，普通 Gateway 和 node exec 调用会在当前工具调用内等待，并在审批后返回命令结果。明确要求异步后续的流程会立即返回 status: "approval-pending" 和一个审批 id。approval-pending 结果表示命令尚未开始，因此只有当已批准的命令实际内联运行时，才会出现前台回退警告。已批准的异步运行会发出命令进度和完成系统事件（Exec running / Exec finished）。被拒绝或超时的审批对主机命令是终态。有关通知行为，请参阅 系统事件与拒绝。

在具有原生审批卡片/按钮的渠道上，代理应首先依赖该原生 UI，并且仅当工具结果明确说明聊天审批不可用或手动审批是唯一路径时，才包含手动 /approve 命令。

允许列表 + 安全 bin¶

手动允许列表执行会匹配已解析的二进制路径 glob 和裸命令名 glob。裸名称仅匹配通过 PATH 调用的命令，因此当命令是 rg 时，rg 可以匹配 /opt/homebrew/bin/rg，但不匹配 ./rg 或 /tmp/rg。

当 security=allowlist 时，仅当每个管道段都在允许列表中或为安全 bin 时，shell 命令才会被自动允许。在允许列表模式下，除非每个顶层段都满足允许列表（包括安全 bin），否则链式调用（;、&&、||）和重定向会被拒绝。重定向仍不受支持。持久的 allow-always 信任不会绕过该规则：链式命令仍要求每个顶层段都匹配。

autoAllowSkills 是 exec 审批中一个独立的便捷路径，与手动路径允许列表条目不同。对于严格的显式信任，请保持 autoAllowSkills 处于禁用状态。

将这两个控制用于不同任务：

• tools.exec.safeBins：小型、仅 stdin 的流过滤器。
• tools.exec.safeBinTrustedDirs：用于安全 bin 可执行文件路径的显式额外受信任目录。
• tools.exec.safeBinProfiles：用于自定义安全 bin 的显式 argv 策略。
• 允许列表：对可执行文件路径的显式信任。

不要将 safeBins 视为通用允许列表，也不要添加解释器/运行时二进制文件（例如 python3、node、ruby、bash）。如果需要这些，请使用显式允许列表条目，并保持审批提示启用。

openclaw security audit 会在解释器/运行时 safeBins 条目缺少显式 profile 时发出警告，openclaw doctor --fix 可以生成缺失的自定义 safeBinProfiles 条目。openclaw security audit 和 openclaw doctor 还会在你显式将 jq 等宽泛行为 bin 重新加入 safeBins 时发出警告（jq 可以读取环境数据，并可以从模块或启动文件加载 jq 代码，因此请优先使用显式允许列表条目或受审批控制的运行）。即使显式列出，jq 也会作为安全 bin 被拒绝。如果你显式允许列表解释器，请启用 tools.exec.strictInlineEval，以在 普通审批路径 上要求对已识别的内联形式进行审阅者或显式审批。

有关完整策略细节和示例，请参阅 Exec 审批 和 安全 bin 与允许列表。

示例¶

前台：

{ "tool": "exec", "command": "ls -la" }

后台 + 轮询：

{"tool":"exec","command":"npm run build","background":true}
{"tool":"process","action":"poll","sessionId":"<id>","timeout":30000}

当没有自动完成唤醒可用时，使用 process poll 进行按需状态查询和有界等待。避免快速状态循环；在等待当前任务所需的结果时，请传入超时时间。如果启用了自动完成唤醒，则命令在发出输出或失败时可以唤醒会话。

发送按键（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"]}

对于文本，使用 literal。对于精确输入字节，使用 hex。混合请求会按以下顺序发送：literal UTF-8 文本、hex 字节，然后是指定按键：

{
  "tool": "process",
  "action": "send-keys",
  "sessionId": "<id>",
  "literal": "hello ",
  "hex": ["c3", "a9"],
  "keys": ["Enter"]
}

提交（仅发送 CR）：

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

粘贴（默认使用 bracketed 模式）：

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

apply_patch¶

apply_patch 是 exec 的一个子工具，用于结构化的多文件编辑。它默认启用，并且对任何模型提供商可用。allowModels 可以限制它。仅当你想禁用它或将其限制到特定模型时，才使用配置：

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

说明：

• 工具策略仍然适用。allow: ["write"] 隐式允许 apply_patch。
• deny: ["write"] 不会拒绝 apply_patch。当需要同时阻止 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）。设置后，只有匹配的模型会获得该工具。未设置时，所有模型都会获得它。

相关¶

• 执行审批 — shell 命令的审批关卡
• 沙箱 — 在沙箱环境中运行命令
• 后台进程 — 长时间运行的 exec 和 process 工具
• 安全 — 工具策略和提权访问
• 代码模式 — 模型编写程序以调用隐藏工具目录的运行时
• apply_patch — 应用结构化编辑，而不是调用 shell
• Tokenjuice — 压缩大型命令输出