Exec 工具
在工作区中运行 shell 命令。exec 是一个具有变更能力的 shell 接口:只要所选主机或沙箱文件系统允许,命令就可以创建、编辑或删除文件。禁用 OpenClaw 的文件系统工具(如 write、edit 或 apply_patch)并不会使 exec 变成只读。
支持通过 process 进行前台和后台执行。如果 process 被禁用,exec 将同步运行并忽略 yieldMs/background。后台会话按 agent 进行作用域划分。process 只能看到来自同一 agent 的会话。
已完成的调用会直接返回命令输出。只有当 exec 报告命令仍在运行并提供 sessionId 时才使用 process;命令打印的标识符只是普通输出,不是进程句柄。
由操作系统信号终止的无头 node 主机命令会在结果中包含信号名称,即使没有可用的数字退出码。终止前打印的输出并不表示命令已成功。
参数¶
commandstring (path) required- 要运行的 Shell 命令。 Gateway 托管的命令如果包含字面 NUL(U+0000),会在进程启动前返回错误;请修正命令后重试。 空参数、换行符和字面反斜杠零文本仍然有效,且不会被重写。
workdirstring (path) 默认值:cwd- 命令的工作目录。对于本地执行,相对路径会相对于会话的默认 cwd 进行解析;
.保持该目录。路径是字面量,因此不会展开~。 envobject (path)- 键/值环境变量覆盖,合并到继承的环境之上。
yieldMsnumber (path) 默认值:10000- 在此延迟(毫秒)后返回一个正在运行的进程句柄。在 Gateway 及其沙箱中,普通的 yield 命令仍由其请求所拥有:浏览器的 Stop 按钮和输入的
/stop会取消它。正常模型完成则让它继续运行。 backgroundboolean (path) 默认值:false- 立即启动一个刻意独立的服务。请求 Stop 会让它继续运行;请使用其进程句柄单独停止它。对于普通工作,请使用
yieldMs。工具返回后,进程超时仍然适用。 timeoutSecondsnumber (path) 默认值:tools.exec.timeoutSeconds-
以秒为单位限制命令的总生命周期,覆盖本次调用配置的 exec 超时。即使
background或yieldMs已返回会话 ID,超时仍会终止进程。yieldMs控制工具在转入后台前等待多长时间。process工具的timeout控制轮询等待多长时间,同样以毫秒为单位。适用于 gateway、sandbox 和 node 上的
system.run执行。timeoutSeconds: 0会禁用该次调用的 exec 进程超时。对于 gateway 或沙箱中的持久服务,请使用background: true配合timeoutSeconds: 0,完成后用process的kill操作停止它。禁用此超时并不会让进程在主机或 worker 关闭后继续存活。Codex 前台
node_exec继承此预算,包括按 agent 的默认值, 而不是普通的动态工具超时。即使命令计时器被禁用,node 传输等待仍受限制; Stop 和回合取消仍然适用。 参见 Codex 超时。 ptyboolean (path) 默认值:false- 在可用时于伪终端中运行。适用于仅支持 TTY 的 CLI、编码 agent 和终端 UI。
host'auto' | 'sandbox' | 'gateway' | 'node' (path) 默认值:auto-
在哪里执行。省略
host或使用auto来继承配置的 exec 主机,包括 agent 和会话级覆盖。当配置的主机也是auto时,如果沙箱运行时处于活动状态则解析为sandbox,否则解析为gateway。需要沙箱的会话无论配置的主机是什么,都会保持沙箱化。面向模型的 schema 和 code 模式签名只列出会话主机策略允许的主机,并在没有沙箱运行时处于活动状态时省略
sandbox。这些选择在工具创建时被捕获。Node 连通性在执行时检查。 ask'off' | 'on-miss' | 'always' (path)- 基准 ask 模式由
tools.exec.mode和主机审批派生而来。对于来自 channel 的模型调用,当有效主机 ask 为off时,单次调用的ask会被忽略。否则它只会向更严格的模式收紧。 nodestring (path)- 当
host=node时的 Node id/name。 elevatedboolean (path) 默认值:false- 请求提升模式:当操作者允许时,逃离沙箱到配置的主机路径。只有在有效的 security 和 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。仅当当前会话/提供者启用了提升访问时才可用。gateway/node审批由主机审批文件控制。node需要已配对且已连接、支持system.run的 node(companion app 或 headless node 主机)。未设置目标时,exec 会选择唯一符合条件的 node。如果连接了多个符合条件的 node,请设置exec.node、tools.exec.node或/exec node=...来选择一个。它绝不会使用活动 Canvas 目标。显式或绑定的目标本身必须已连接且可执行。完成的结果会在命令输出旁标识所选的 node。exec host=node是 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 该快照。看起来像秘密的变量会被排除。内存缓存最多保留 128 个最近使用的快照键;被淘汰的键可以复用磁盘上的新快照。沙箱和 node exec 不使用此快照。在 Gateway 进程环境中设置OPENCLAW_EXEC_SHELL_SNAPSHOT=0可禁用此快照路径。 - 主机执行(
gateway/node)会拒绝env.PATH和加载器覆盖(LD_*/DYLD_*),以防止二进制劫持或注入代码。 - 精确的
"cat"或空的GIT_PAGER和PAGER覆盖会被规范化为空值,包括在 node shell-wrapper 执行中。这会在不通过PATH传递可执行分页器名称的情况下禁用 Git 分页。其他程序可能将空的PAGER解释为不同含义。需要时请使用它们的非交互标志。其他分页命令、路径、空白变体和MANPAGER覆盖仍会被阻止。 - OpenClaw 会在生成的命令环境中设置
OPENCLAW_SHELL=exec(包括 PTY 和沙箱执行),以便 shell/profile 规则能够检测 exec 工具上下文。 - 在默认关闭的 secret 出口代理 下,Gateway 托管的 exec 只会将 shared-store 中的
secret条目作为进程本地哨兵接收。经过认证的回环代理会在出站 HTTPS 请求时替换为明文。每个受管进程都有自己的代理授权,该授权在发起回合结束后仍然有效,并在进程退出、取消、超时或 Gateway 关闭时被撤销。 - shared-store 中的
env条目故意以明文形式存在,并从下一次 agent 运行开始到达 Gateway 托管的 exec。它们不会到达沙箱、远程node、ACP 或 Codex 原生 shell 执行。在 Codex harness 下,请使用gateway_exec走这条由 OpenClaw 管理的环境路径。 - 使用 受管 GitHub 身份 时,Gateway 托管的 exec 会验证所选 profile,并在每次进程启动时私有地绑定其凭据。不可用的 profile 会以重连指引阻止该本地执行,而不是回退到原生 keyring 凭据。正在运行的 shell 会保留其启动令牌。后续 exec 启动会观察到刷新。Codex 原生 shell 不共享此启动绑定。
- 沙箱化 exec 会排除该身份,除非
agents.entries.<id>.tools.github.allowInSandbox: true。这个仅限 agent 的选择加入支持 Docker 和 Podman,包括需要角色的沙箱:profile 以只读方式挂载在/openclaw/github,命令会收到其受管令牌和 Git author。有效的共享 scope 会以警告拒绝注入;安全审计会对每次选择加入发出警告。参见 sandbox GitHub 身份。 - Secret egress 会设置
NODE_USE_ENV_PROXY=1,以便受支持的 Node.js 全局fetch客户端遵循进程作用域的代理。它不使用NODE_OPTIONS。 - 对于来自 channel 的运行,当 channel 提供了这些 id 时,OpenClaw 还会在
OPENCLAW_CHANNEL_CONTEXT中暴露一个窄范围的发送者/聊天身份 JSON 载荷。 - 有能力的 node 会独立于自定义环境覆盖接收 channel/subagent 路由上下文,并自行注入固定标记。有关能力协商和混合版本行为,请参见 node 执行上下文。
exec无法运行openclaw channels login或/approveshell 命令:openclaw channels login是交互式 channel 认证流程,而/approve需要通过审批命令处理器处理,而不是 shell。请在 gateway 主机的终端中运行 channel 登录,或使用 channel 专用的登录 agent 工具(如果存在,例如whatsapp_login)。- 重要:沙箱化默认关闭。如果沙箱化关闭,隐式
host=auto会解析为gateway。显式host=sandbox仍然会安全失败(fail closed),而不是静默地在 gateway 主机上运行。请启用沙箱化,或使用host=gateway并配合审批。 - Python 脚本预检只检查常见 shell 语法错误,并且只检查有效
workdir边界内的文件。如果脚本路径解析到workdir之外,则会跳过文件检查。JavaScript 源码交给 Node 处理,由 Node 返回其常规诊断和退出码;运行时错误之前的语句可能已经执行。对不明确的 Python/Node 解释器命令的单独限制仍然适用。当host=gateway且有效策略为security=full且ask=off时,预检会完全跳过。 - 对于现在开始的长时运行工作,请只启动一次,并在启用了自动完成唤醒且命令产生输出或失败时依赖它。使用
process查看日志、状态、输入或进行干预。不要用 sleep 循环、超时循环或重复轮询来模拟调度。 -
当
tools.exec.notifyOnExit=false时,运行中的结果会以文本和结构化followUp两种方式明确说明自动完成唤醒已禁用。在命令运行期间,后续的process poll、log和list结果会使用命令启动时捕获的策略保留该指引。如果任务需要结果,请在结束回合前使用process poll并在超时内收集它,除非已经安排了其他续接。正在运行的进程或活动的会话目标并不会安排该续接。 -
当已批准的异步命令完成时,其后续处理使用来自
agents.defaults.timeoutSeconds的常规 agent 运行超时。后续观察者可以在已接受的 agent 运行继续时结束等待。 - 子 agent 会话不会收到自动的后台 exec 唤醒。如果没有其他完成源,请在让出前使用
process poll收集结果。 - 进程所有者跟踪由 agent 启动的后台命令。使用返回的进程会话 ID 来检查输出、轮询或停止命令;其完成可以唤醒 agent。
- 对于应稍后或按计划执行的工作,请使用 cron,而不是
execsleep/delay 模式。
配置¶
| 键 | 默认值 | 说明 |
|---|---|---|
tools.exec.timeoutSeconds |
1800 |
每条命令的默认 exec 超时时间(秒)。每次调用中的 timeoutSeconds 会覆盖它;每次调用中的 timeoutSeconds: 0 会禁用 exec 进程超时。 |
tools.exec.host |
auto |
当沙箱运行时处于活动状态时解析为 sandbox,否则解析为 gateway。 |
tools.exec.mode |
由 host 派生 | 规范策略开关。见下文 模式。 |
tools.exec.reviewer.model |
已配置的 agent 主模型 | 用于 mode=auto 审查的可选 provider/model 覆盖。 |
tools.exec.reviewer.timeoutMs |
30000 |
在回退到人工之前,审查模型准备和完成各阶段的超时时间。 |
tools.exec.node |
未设置 | 按 id、名称或 IP 选择哪个已配对节点运行 host=node 命令。仅当连接了多个符合条件的节点时需要;见 参数。 |
tools.exec.notifyOnExit |
true |
为 true 时,后台化的 host exec 会话在退出时会在其源会话中通过一个普通回合继续。 |
tools.exec.approvalRunningNoticeMs |
10000 |
当需要审批的 exec 运行时间超过该值时,发出一次“运行中”通知(0 表示禁用)。 |
tools.exec.strictInlineEval |
false |
见 内联 eval。 |
tools.exec.commandHighlighting |
false |
为 true 时,审批提示可以高亮命令文本中由解析器派生的命令片段。可全局设置或按 agent 设置;不会改变审批策略。 |
tools.exec.pathPrepend |
未设置 | 要前置到 PATH 的目录,用于 gateway、sandbox 以及拥有的本地原生 Codex 命令。 |
tools.exec.safeBins |
未设置 | 仅通过 stdin 运行的安全二进制文件,可在没有显式 allowlist 条目的情况下运行。见 安全 bins。 |
tools.exec.safeBinTrustedDirs |
/bin, /usr/bin |
用于 safeBins 路径检查的额外显式可信目录。PATH 条目永远不会自动可信。 |
tools.exec.safeBinProfiles |
未设置 | 每个安全 bin 的可选自定义 argv 策略(minPositional、maxPositional、allowedValueFlags、deniedFlags)。 |
无审批 host exec 是 gateway 和 node 的默认值(mode=full)——这来自 host 策略默认值,而不是来自 host=auto。如果你想要审批/allowlist 行为,请设置 tools.exec.mode 并收紧 host 审批文件。见 Exec 审批。要强制使用 gateway 或 node 路由,无论沙箱状态如何,请设置 tools.exec.host 或使用 /exec host=...。
示例:
模式¶
tools.exec.mode 是规范化的持久化策略开关。运行时安全和审批行为由它派生。
| 模式 | 安全 | 询问 | 行为 |
|---|---|---|---|
deny |
deny |
off |
Exec 被拒绝。 |
allowlist |
allowlist |
off |
仅运行 allowlist/safe-bin 命令;其他命令不会询问。 |
ask |
allowlist |
on-miss |
allowlist 匹配项直接运行;其他所有内容都会询问人工。 |
auto |
allowlist |
on-miss |
allowlist/safe-bin 匹配项直接运行;符合条件的未匹配项会从原生审查器获得 allow、deny 或 ask 判定。 |
| 模式 | 安全 | 询问 | 行为 |
|---|---|---|---|
full |
full |
off |
无普通策略提示;参见 严格内联 eval. |
在消息中使用 /exec ask=always 可要求该次运行需人工批准。它不会延续到后续消息。使用 会话权限模式 配置会话级策略。
自动审查批准是一次性的。审查器返回 allow、deny 或 ask:allow 仅允许运行一次低或中风险命令。deny 会向代理返回原因,代理必须选择实质更安全的替代方案或询问用户,而不是绕过拒绝。ask 请求人工批准。包含审查器指示文本的命令会被拒绝并返回给代理,以便其重写命令。它们不会直接升级为人工批准。审查器故障、超时和无效响应也会请求人工处理。在网关上,同一会话中连续三次审查器拒绝会将第三条命令升级为人工批准。审查器允许或已解决的人工批准会重置计数。
将 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 下使用。它也适用于基于模型的 widget 审查,但不会配置 Codex 的原生 Guardian 审查器。
将 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 调用和 widget,对话上下文不可用。
在网关上,命令在审查前仍必须通过现有的可变文件绑定检查。这些检查仍会拒绝 here-doc、未解析的可执行文件和缺失的脚本操作数。整个普通外部分发链——每个原始包装器可执行文件和最终命令段可执行文件——在审查时绑定,并在启动前重新检查:受保护可执行文件仅使用解析后的真实路径标识,而可写可执行文件还使用内容哈希。可执行文件解析发生变化(包括 PATH 中更靠前的新可执行文件)会拒绝已批准的运行。已提交的主机批准策略也会在最终进程生成边界重新验证,包括异步启动工作之后和 PTY 回退之前。策略撤销会阻止待启动的进程;它不会停止已经启动的进程。仅标识绑定不会使原本有效的人工批准变为一次性。
审查器批准的未固定执行要求完整分发链进行标识绑定:授权计划必须完整、使用直接传输,并为每个包装器和最终可执行文件记录可执行文件操作数。符合条件的 glob 和链保留其参数展开,同时每个包装器和可执行文件固定到其绑定的绝对调用路径。可执行文件符号链接保留其调用语义(包括 Python 虚拟环境),同时其规范目标和可变内容仍保持绑定并重新验证。从授权计划重建的命令使用已准备的运行时环境,而不加载 shell 启动快照,因此别名、函数和启动 PATH 更改无法替换已批准的分发。普通 full 模式命令保留 shell 启动自定义。节点主机自动审查接受已准备的固定直接命令,包括节点自身的规范 POSIX shell 传输,围绕一个具有静态参数的直接绝对可执行文件。当网关无法检查节点的内存绑定时,裸可执行文件名、未加引号的 glob 和用户提供的包装器仍需要人工批准。节点可执行文件标识重新验证覆盖从本地策略评估到分发的过程。节点主机启动也会在异步准备后重新验证已提交的批准策略。它不会在远程人工批准等待期间保留每个内部 shell 可执行文件的标识。有关该边界,参见 解释器/运行时命令。
Shell -c 包装器、带赋值的 env、xcrun、BusyBox/Toybox applet、shell builtin/command/exec 分发以及任何其他不完整分发链都会跳过审查器,并返回 Exec auto-review skipped: dispatch chain cannot be bound。在自动模式下,当现有绑定检查成功时,这些形式会采用一次性人工批准路径。现有绑定拒绝仍然适用。当完整链已绑定时,普通命令和不带赋值的透明 env 仍符合条件。没有持久化数据模型更改:绑定在批准生命周期内保持在内存中。
请求命令中的 POSIX 登录 shell 或交互式 shell 包装器永远不会接受自动审查。当绑定成功时(例如 bash -lc 'printf ok'),它们需要人工审批,因为其隐式启动文件位于操作数绑定之外。已有的绑定拒绝仍然优先。被作为代码加载选项拒绝的交互式形式仍保持拒绝。这适用于请求命令中的包装器。Gateway 的普通 shell 启动快照保持不变。
显式 ask=always 以及超过审查候选上限的命令会直接进入人工审批。
Codex app-server 命令审批如果尚未由显式运行时或原生策略决定,则使用人工审批路径。OpenClaw 不会为这些请求运行其配置的 exec 审查器,因为 Codex 未暴露可强制执行的已解析可执行文件,无法将审查决定绑定到 Codex 实际运行的命令。
内联 eval(strictInlineEval)¶
tools.exec.strictInlineEval 是一个独立的可选启用设置,默认值为 false。当普通 host 审批评估运行时,启用它要求对已识别的内联解释器 eval 形式进行审查器或显式审批,即使 exec 和 host 策略允许 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 审批路径可能允许原生自动审查器放行低风险或中风险的一次性命令。直接 node-host system.run 调用仍需要显式审批,因为它们无法将命令交给人工审批路径。审查器拒绝会附带原因返回给 agent。ask 会转交给人工。allow-always 仍可以持久化无害的解释器/脚本调用,但内联 eval 形式不会成为持久允许规则。
仅配置 tools.exec.mode: "full" 不会跳过此检查。Gateway 执行在以下任一情况下会跳过 host 审批路径:
- 完全权限会话保持有效安全级别为
full,且 ask 为off。 - 允许 elevated-full 执行,并且 exec 策略和 host 审批都允许
full/off。
这些路径会跳过检测严格内联 eval 的审批所有者。收紧 full 会话的 ask 模式会恢复该评估,即使该会话仍然绕过 host 审批文件下限。参见 会话权限模式 和 提升模式。
对于普通配置的 full/off 执行且不对这些形式进行提示,请保持 strictInlineEval 未设置或将其设置为 false。当检测运行时,askFallback: "full" 不满足严格内联 eval 审批。
PATH 处理¶
Gateway 托管的命令使用与正在运行的 Gateway 安装绑定的 openclaw 启动器。源码检出会将任何继承的 TSX 预加载固定到该检出,在 Node 和 Bun 上均如此,因此该启动器也可以从检出之外的 agent 工作区运行。
已准备好的子命令在启动前会解析启动器的具体路径。
在更新期间切换安装符号链接不会重定向
已经准备好的命令。新的 openclaw 调用会遵循更新后的链接。
host=gateway:将你的登录 shellPATH合并到 exec 环境中。host 执行会拒绝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。host 执行会拒绝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:设备 页面包含一个小型“Exec node 绑定”面板,用于相同设置。已保存的目标可能变得无法解析或停止广播执行支持。其绑定随后保持选中,并标记为 不可用。即使没有可执行 node 可用,你也可以使用 任意 node 或 使用默认 清除它。受支持的名称、地址和 ID 前缀可以解析,而无需重写已保存的引用。
Python 环境(uv)¶
在 uv 管理的项目 中,单独的 python 或 python3 会使用 exec host 的 PATH 选择的解释器。如果项目环境不在该路径上,导入安装在该环境中的依赖项可能会因 ModuleNotFoundError 而失败。
Set workdir 为项目目录,并运行 uv run python3 script.py 以使用其环境。当项目环境已在 PATH 中时,直接使用解释器也可以。
对于重复的代理工作,请将项目约定记录在工作区的 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 仅对通过频道允许列表/配对和访问组授权的授权发送者生效。访问组强制执行始终开启。它不会写入配置。授权的外部频道发送者可以持久化放置默认值。内部网关/webchat 客户端需要 operator.admin 才能执行此操作。回合范围的 security 和 ask 不需要该持久化权限。
单独的 /exec security=deny 会确认仅运行设置,但不会启动代理运行,也不会影响下一条消息。使用会话权限模式 可在消息之间保持策略。
sessions.patch 和 sessions.patchMany 中的 execSecurity 和 execAsk 字段已在 2026.8.1 中退役。它们仍保留在协议 v4 的 wire schema 中,但包含任一字段(包括 null)的请求都会以 INVALID_REQUEST 和替换建议被拒绝。设置 permissionMode(read-only、guarded、workspace 或 full)以设置会话范围策略,或在消息中使用 /exec 进行单次运行。
当会话具有权限模式时,按回合的 /exec 覆盖只能收紧其安全和审批策略。例如,/exec security=deny 即使在全访问会话中也会阻止该回合的 exec。请求更宽松安全或更少审批的覆盖不会改变会话模式的限制。全访问会话仅在有效安全级别保持为 full 时绕过主机审批文件下限。仅收紧 ask 仍会应用所请求的审批级别,而不会恢复这些下限。
若要彻底禁用 exec,请通过工具策略拒绝它(tools.deny: ["exec"] 或按代理)。除上述全访问会话例外外,主机审批文件下限仍然适用。
Exec 审批(伴侣应用 / 节点主机)¶
沙箱代理可以在 exec 在网关或节点主机上运行之前要求按请求审批。有关策略、允许列表和 UI 流程,请参阅 Exec 审批。
当可以送达人工审批时,普通 Gateway 和节点 exec 调用会在当前工具调用内等待,并在批准后返回命令结果。明确请求异步后续的流程会立即返回 status: "approval-pending" 和一个审批 id。approval-pending 结果表示命令尚未开始,因此只有当已批准的命令实际内联运行时,才会出现前台回退警告。已批准的异步运行会发出命令进度和完成系统事件(Exec running / Exec finished)。被拒绝或超时的审批对主机命令是终态的。有关通知行为,请参阅 系统事件和拒绝。
在具有原生审批卡片/按钮的频道上,代理应首先依赖该原生 UI,并且仅当工具结果明确说明聊天审批不可用或手动审批是唯一途径时,才包含手动 /approve 命令。
允许列表 + 安全 bin¶
手动允许列表执行会匹配已解析的二进制路径通配符和裸命令名称通配符。裸名称仅匹配通过 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)。如果需要这些,请使用显式允许列表条目并保持审批提示启用。
当解释器/运行时 safeBins 条目缺少显式配置文件时,openclaw security audit 会发出警告,并且 openclaw doctor --fix 可以生成缺失的自定义 safeBinProfiles 条目。当你显式将具有广泛行为的 bin(例如 jq)重新添加到 safeBins 时,openclaw security audit 和 openclaw doctor 也会发出警告(jq 可以读取环境数据,并可以从模块或启动文件加载 jq 代码,因此请优先使用显式允许列表条目或受审批控制的运行)。即使显式列出,jq 也会作为安全 bin 被拒绝。如果你显式将解释器加入允许列表,请启用 tools.exec.strictInlineEval,以要求在普通审批路径上对识别出的内联形式进行审阅者或显式审批。
有关完整策略详情和示例,请参阅 Exec 审批 和 安全 bin 与允许列表。
示例¶
前台:
产生句柄的普通工作,然后轮询:
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"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。混合请求按顺序发送字面量 UTF-8 文本、十六进制字节,然后是命名按键:
{
"tool": "process",
"action": "send-keys",
"sessionId": "<id>",
"literal": "hello ",
"hex": ["c3", "a9"],
"keys": ["Enter"]
}
提交(仅发送 CR):
粘贴(默认使用括号模式):
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)。设置后,只有匹配的模型会获得该工具。未设置时,所有模型都会获得该工具。
相关¶
- 执行审批 — shell 命令的审批门控
- 沙箱 — 在沙箱环境中运行命令
- 后台进程 — 长时间运行的 exec 和 process 工具
- 安全 — 工具策略和提权访问
- 代码模式 — 模型编写程序以调用隐藏工具目录的运行时
apply_patch— 应用结构化编辑,而不是通过 shell 执行- Tokenjuice — 压缩大型命令输出
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw