OpenClaw工具拆解之exec

如果文章对你有帮助，请点个“关注”

一、工具概述

功能：执行 shell 命令（最核心的基础工具）
核心特性：

• 支持后台运行（yieldMs/background）
• 支持超时控制（timeout）
• 支持 PTY 模式（pty=true 用于 TTY 命令）
• 支持多主机（sandbox/gateway/node）
• 支持提权执行（elevated）
• 支持安全模式（deny/allowlist/full）
• 支持审批模式（off/on-miss/always）
• 支持环境变量（env）
• 支持工作目录（cwd/workdir）

二、Schema 定义

位置：第 14782 行

constexecSchema=Type.Object({command:Type.String({description:"Shell command to execute"}),workdir:Type.Optional(Type.String({description:"Working directory (defaults to cwd)"})),env:Type.Optional(Type.Record(Type.String(),Type.String())),yieldMs:Type.Optional(Type.Number({description:"Milliseconds to wait before backgrounding (default 10000)"})),background:Type.Optional(Type.Boolean({description:"Run in background immediately"})),timeout:Type.Optional(Type.Number({description:"Timeout in seconds (optional, kills process on expiry)"})),pty:Type.Optional(Type.Boolean({description:"Run in a pseudo-terminal (PTY) when available (TTY-required CLIs, coding agents)"})),elevated:Type.Optional(Type.Boolean({description:"Run on the host with elevated permissions (if allowed)"})),host:Type.Optional(Type.String({description:"Exec host (sandbox|gateway|node)."})),security:Type.Optional(Type.String({description:"Exec security mode (deny|allowlist|full)."})),ask:Type.Optional(Type.String({description:"Exec ask mode (off|on-miss|always)."})),node:Type.Optional(Type.String({description:"Node id/name for host=node."}))});

三、完整执行代码

位置：第 16558 行

functioncreateExecTool(defaults){// 1. 解析默认配置constdefaultBackgroundMs=clampWithDefault(defaults?.backgroundMs??readEnvInt("PI_BASH_YIELD_MS"),1e4,10,12e4);constallowBackground=defaults?.allowBackground??true;constdefaultTimeoutSec=typeofdefaults?.timeoutSec==="number"&&defaults.timeoutSec>0?defaults.timeoutSec:1800;// 2. 解析安全策略（白名单、黑名单等）const{safeBins,safeBinProfiles,trustedSafeBinDirs}=resolveExecSafeBinRuntimePolicy({...});// 3. 返回工具定义return{name:"exec",label:"exec",description:"Execute shell commands with background continuation. Use yieldMs/background to continue later via process tool. Use pty=true for TTY-required commands (terminal UIs, coding agents).",parameters:execSchema,execute:async(_toolCallId,args,signal,onUpdate)=>{// === 执行逻辑开始 ===constparams=args;// 1. 参数验证if(!params.command)thrownewError("Provide a command to start.");// 2. 解析后台运行请求constbackgroundRequested=params.background===true;constyieldRequested=typeofparams.yieldMs==="number";constyieldWindow=allowBackground?(backgroundRequested?0:clampWithDefault(params.yieldMs??defaultBackgroundMs,defaultBackgroundMs,10,12e4)):null;// 3. 解析提权请求constelevatedRequested=elevatedMode!=="off";if(elevatedRequested){if(!elevatedDefaults?.enabled||!elevatedDefaults.allowed){thrownewError("elevated is not available right now...");}}// 4. 确定执行主机（sandbox/gateway/node）lethost=requestedHost??configuredHost;if(elevatedRequested)host="gateway";// 5. 确定安全模式letsecurity=minSecurity(configuredSecurity,normalizeExecSecurity$1(params.security)??configuredSecurity);if(elevatedRequested&&elevatedMode==="full")security="full";// 6. 确定审批模式letask=maxAsk(configuredAsk,normalizeExecAsk$1(params.ask)??configuredAsk);constbypassApprovals=elevatedRequested&&elevatedMode==="full";if(bypassApprovals)ask="off";// 7. 解析工作目录constrawWorkdir=params.workdir?.trim()||defaults?.cwd||process.cwd();letworkdir=rawWorkdir;if(sandbox){constresolved=awaitresolveSandboxWorkdir({workdir:rawWorkdir,sandbox,warnings});workdir=resolved.hostWorkdir;}// 8. 解析环境变量（安全检查）constenv=sandbox&&host==="sandbox"?buildSandboxEnv({...}):hostEnvResult?.env??inheritedBaseEnv;// 9. 处理不同主机的执行逻辑if(host==="node"){returnexecuteNodeHostCommand({...});}if(host==="gateway"&&!bypassApprovals){// 10. Gateway 白名单检查（可能需要用户审批）constgatewayResult=awaitprocessGatewayAllowlist({...});if(gatewayResult.pendingResult){// 需要审批，返回待处理状态returngatewayResult.pendingResult;}execCommandOverride=gatewayResult.execCommandOverride;}// 11. 执行命令construn=awaitrunExecProcess({command:params.command,execCommand:execCommandOverride,workdir,env,sandbox,containerWorkdir,usePty:params.pty===true&&!sandbox,warnings,maxOutput:DEFAULT_MAX_OUTPUT,pendingMaxOutput:DEFAULT_PENDING_MAX_OUTPUT,notifyOnExit,notifyOnExitEmptySuccess,timeoutSec:effectiveTimeout,onUpdate});// 12. 处理后台运行letyielded=false;letyieldTimer=null;constonYieldNow=()=>{if(yieldTimer)clearTimeout(yieldTimer);if(yielded)return;yielded=true;markBackgrounded(run.session);resolveRunning();};if(allowBackground&&yieldWindow!==null){if(yieldWindow===0)onYieldNow();elseyieldTimer=setTimeout(onYieldNow,yieldWindow);}// 13. 等待执行完成returnnewPromise((resolve,reject)=>{run.promise.then((outcome)=>{if(yieldTimer)clearTimeout(yieldTimer);if(yielded||run.session.backgrounded)return;resolve(buildExecForegroundResult({outcome,cwd:run.session.cwd,warningText:getWarningText()}));}).catch((err)=>{if(yieldTimer)clearTimeout(yieldTimer);if(yielded||run.session.backgrounded)return;reject(err);});});}};}

四、执行流程图

exec 工具调用 ↓ 1. 参数验证（command 必填） ↓ 2. 解析后台运行请求（background/yieldMs） ↓ 3. 解析提权请求（elevated） ↓ 4. 确定主机（sandbox/gateway/node） ↓ 5. Gateway 白名单检查 ├─ 需要审批 → 返回 pending 状态，等待用户 /approve └─ 无需审批 → 继续 ↓ 6. 启动进程（runExecProcess） ├─ 创建子进程 ├─ 监听输出 ├─ 记录日志 └─ 返回 session ↓ 7. 判断是否后台运行 ├─ 是 → 立即返回"正在运行"，用户可用 process 工具管理 └─ 否 → 等待完成，返回完整输出

五、返回结果格式

前台运行完成

{"content":[{"type":"text","text":"命令输出内容..."}],"details":{"status":"completed","exitCode":0,"cwd":"/path/to/workdir"}}

后台运行中

{"content":[{"type":"text","text":"Command still running (session abc123, pid 12345). Use process (list/poll/log/write/kill/clear/remove) for follow-up."}],"details":{"status":"running","sessionId":"abc123","pid":12345,"startedAt":1711716000000,"cwd":"/path/to/workdir","tail":"部分输出..."}}

需要审批

{"content":[{"type":"text","text":"Approval required (id abc123).\nHost: gateway\nCWD: /workspace\nCommand:\n```sh\nrm -rf /tmp/test\n```\nReply with: /approve abc123 allow-once|allow-always|deny"}],"details":{"status":"pending_approval","approvalId":"abc123"}}

六、参数详解

6.1 必填参数

6.2 可选参数

七、使用示例

7.1 简单命令

{"name":"exec","arguments":{"command":"ls -la"}}

7.2 后台运行

{"name":"exec","arguments":{"command":"python long_running_script.py","yieldMs":5000}}

7.3 超时控制

{"name":"exec","arguments":{"command":"ping -n 100 www.example.com","timeout":30}}

7.4 PTY 模式

{"name":"exec","arguments":{"command":"htop","pty":true}}

7.5 环境变量

{"name":"exec","arguments":{"command":"echo $MY_VAR","env":{"MY_VAR":"Hello World"}}}

八、安全机制

8.1 安全模式

8.2 审批模式

8.3 提权执行

{"name":"exec","arguments":{"command":"apt update","elevated":true,"host":"gateway"}}

前提条件：

• elevatedDefaults.enabled = true
• elevatedDefaults.allowed = true

九、配套工具

process 工具

exec 的配套工具，用于管理后台进程：

如果文章对你有帮助，请点个“关注”