OpenClaw 后台进程管理exec 与 process 工具的实现机制与实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 通过exec工具执行 Shell 命令并用内存中的进程注册表承载长时任务process工具则负责对这些后台会话进行轮询、交互与清理。本文完整梳理 exec/process 两个工具的全部参数、环境变量与配置项、Worker 环境下的生命周期规则以及子进程桥接的底层清理机制并结合 OpenClaw 源码中的进程注册表实现帮助你在调试长时任务、管理交互式 CLI 会话时做到心中有数。exec 工具参数与执行行为参数说明参数说明command必填。要执行的 Shell 命令。workdir工作目录省略时使用默认 cwd。env为该命令附加的环境变量。yieldMs等待多少毫秒后转入后台默认 10000。background立即在后台运行。timeoutSeconds超时秒数默认取tools.exec.timeoutSeconds到期即杀进程。对单次调用传timeoutSeconds: 0可禁用该次调用的 exec 进程超时。pty可用时在伪终端中运行适用于需要 TTY 的 CLI、编码类 Agent。elevated当 elevated 模式启用/允许时在沙箱外运行默认走gateway当 exec 目标为node时走node。hostExec 目标auto、sandbox、gateway或node。nodeNode id/name与host: node搭配使用。从源码结构看host的解析遵循单次调用覆盖 → 会话级execHost→ Agent 配置 → 全局tools.exec.host→ 默认auto的优先级链见 exec-defaults.ts。默认超时 1800 秒在 bash-tools.exec-run.ts 中确认defaults.timeoutSec缺省或为 0 时回落到 1800。执行行为前台运行会直接返回保留的输出并显式告知此前输出是否超过了总量上限aggregate cap。当进程被转入后台显式background或yieldMs超时触发时工具返回status: runningsessionId和一段简短的输出尾部。被后台化的调用以及走yieldMs的调用会继承tools.exec.timeoutSeconds除非调用显式传了timeoutSeconds。返回后台会话 ID 并不会停止进程超时。要在 gateway 或沙箱内运行持久化服务应使用background: true搭配timeoutSeconds: 0结束后再用process的kill动作停止它。宿主与 Worker 的生命周期限制仍然生效。输出会驻留在内存中直到达到每会话的聚合上限或被轮询/清除。已结束finished会话在其配置的 TTL 到期后过期TTL 从完成时刻起算。每个 exec 在被接纳admit时捕获当时所属 Agent 的保留期设置用其他 Agent 的 process 工具不会改变既有结果的寿命。注册表最多保留 50 个已结束会话、共 2,000,000 字符的保留输出超限后按最旧记录优先逐出最新的已完成会话即使单条记录超出全局上限也保留其经过截断的每会话聚合输出。这些常量在源码中可以直接找到bash-process-registry.ts 中定义了MAX_FINISHED_SESSION_COUNT 50、MAX_FINISHED_SESSION_OUTPUT_CHARS 2_000_000、DEFAULT_JOB_TTL_MS 30 * 60 * 100030 分钟钳制在 1 分钟到 3 小时之间并有配套的测试 bash-process-registry.test.ts。如果process工具被禁用disallowedexec将同步运行并忽略yieldMs/background。源码中对应 bash-tools.exec-run.ts 的foregroundFallbackWarning逻辑allowBackground为 false 时返回continuation options are unavailable; running synchronously警告。派生的 exec 命令会收到OPENCLAW_SHELLexec环境变量供上下文感知的 shell/profile 规则使用。对于现在就要开始的长时工作启动一次然后在命令产生输出或失败时依赖自动完成唤醒automatic completion wake若已启用。如果自动完成唤醒不可用或你需要对一个干净退出且无输出的命令确认静默成功用process轮询。不要用sleep循环或重复轮询来模拟提醒或延迟跟进——未来的工作交给 cron。环境变量覆盖变量效果OPENCLAW_BASH_YIELD_MS后台化前的默认让出时间ms。默认 10000钳制范围 10–120000。OPENCLAW_BASH_MAX_OUTPUT_CHARS内存中聚合输出的字符上限。默认 200000钳制范围 1000–200000。OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS每个 stdout/stderr 流的待处理输出上限。默认 30000钳制范围 1000–200000且受聚合上限约束。OPENCLAW_BASH_JOB_TTL_MS已结束会话的 TTLms限制在 1 分钟到 3 小时之间。OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS可写后台会话被标记为可能在等待输入之前的空闲输出阈值。默认 15000。源码印证yield 钳制范围在 bash-tools.exec-run.ts 中以clampWithDefault(..., 10_000, 10, 120_000)落实同时兼容旧变量名PI_BASH_YIELD_MSpending 输出默认值DEFAULT_PENDING_OUTPUT_CHARS 30_000与 TTL 钳制函数clampTtl在 bash-process-registry.ts 中。配置项优先于环境变量配置键默认值效果tools.exec.backgroundMs10000等价于OPENCLAW_BASH_YIELD_MS。tools.exec.timeoutSeconds1800每次调用的默认超时。tools.exec.cleanupMs1800000等价于OPENCLAW_BASH_JOB_TTL_MS。tools.exec.notifyOnExittrue后台 exec 退出时入队一个系统事件并请求心跳。tools.exec.notifyOnExitEmptySuccessfalse对成功但无输出的后台运行也入队完成事件。notifyOnExit的解析逻辑见 bash-tools.exec-run.ts仅当显式设为false才关闭。Worker 环境下的后台进程在配对节点paired-node或 node 承载的云端 Worker 上后台进程归属于会话所在的环境结束或取消当前回合turn不会终止已后台化的命令同一环境的后续回合可以用process轮询、发送输入或停止它们前台命令在回合被取消时仍会停止。保留的 Worker 占用一个 node worker 槽位复用它不需要额外槽位。若命令在两个回合之间完成其保留输出对下一个回合仍然可用受常规进程输出上限与 TTL 约束。当一个回合结束时没有存活的后台命令Worker 即退出。迁移或退役环境、替换其归属、或停止节点都会连带停止其进程。进程句柄无法跨越 Worker 或节点重启存活。若节点的配对被吊销或其提供者不再识别该租约lease会话放置会失败。物理清理可能保持 pending直到 OpenClaw 确认该 Worker 确实已停止未确认的停止不会释放其归属记录。Worker 完成目前不会自动唤醒 Gateway 会话请在后续回合用process poll检查结果。关闭 portal 关闭的是它的代理proxy不是开发服务器停止服务器要用process kill。子进程桥接Child Process Bridging在 exec/process 工具之外派生长时子进程时CLI 重启动、gateway 辅助进程应挂接子进程桥接助手使终止信号能够转发、监听器在退出/关闭时解绑。这避免了 systemd 下的孤儿进程并保持跨平台关闭行为一致。关于清理语义文档给出了几条值得注意的保证被监管命令的超时也覆盖启动阶段包括被阻塞的私有输入private-input投递超时结果可能在清理仍在进行时返回。作用域退役与 Gateway 关闭会单独等待清理责任人cleanup owner当该责任人报告不确定uncertainty时按失败上报而不是把超时当作命令已停止的证明。对于归属的 POSIX 进程组清理会等待操作系统在优雅关闭后确认进程组消失。仅命令完成或输出管道关闭并不足以说明其后代进程已停止没有确认清理的强制终止仍保持不确定状态。本地 TUI 的 shell 关闭对自己的命令使用同一个清理责任人。一次性工具的清理会把配置的沙箱运行时保持在 session、agent 或 shared 生命周期上并加入该命令的本地命令传输与后端清理它不会停止 shared 沙箱也不会声称所有远端后代进程已退出。宿主命令包括来自沙箱化会话的 elevated 命令仍需要进程树process-tree级清理。当宿主命令需要进程树清理时pty请求会在启动原生 PTY 之前回退到子进程路径并上报警告确实需要终端的命令在该回退下可能失败。清理失败保持不确定而不会被报告为干净关闭。process 工具动作与行为动作一览动作效果list列出运行中 已结束的会话。poll抽取drain某会话的新输出同时报告退出状态。log读取聚合输出与输入恢复提示支持offsetlimit。write向 stdin 发送数据data可选eof。send-keys向 PTY 承载的会话发送显式按键令牌或字节。submit向 PTY 承载的会话发送回车/换行。paste发送字面文本可选用 bracketed paste 模式包裹。kill终止一个后台会话。clear从内存中移除一个已结束会话。remove运行中则 kill已结束则 clear。行为细节只有被后台化的会话会被列出/保留——纯内存保存不落盘进程重启后会话丢失。重置或删除会话只会清除它已完成的后台进程其他会话、显式 shared 作用域以及运行中的进程不受影响。对应实现为 bash-process-registry.ts 中按 scope 清除clearFinishedSessionsForScopes。存活的后台会话会阻止协作式宿主挂起cooperative host suspension与安全的 Gateway 重启直到进程责任人确认其实际退出。process remove可能在请求终止后立即隐藏一个运行中的会话挂起与重启的阻塞会持续到退出确认。这一点在 markExited 中体现即使可见性被清除activeExecSessions仍通过hasActiveBackgroundExecSession报告进程活性。会话日志只有在你执行process poll/log且工具结果被记录时才会保存进聊天历史。process按 Agent 作用域隔离只能看到该 Agent 启动的会话。当自动完成唤醒不可用时用poll/log获取状态、日志或完成确认。恢复交互式 CLI 前先执行log使当前转写、stdin 状态与输入等待提示能一起看到。需要输入或干预时使用write/send-keys/submit/paste/kill。process list包含派生出的name命令动词 目标便于快速浏览。process list、poll、log仅当会话的 stdin 仍可写且空闲超过输入等待阈值默认 15000 msOPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS时才报告waitingForInput。process log采用基于行的offset/limit两者都省略时返回最后 200 行并附分页提示只设offset未设limit时从offset返回到末尾不做 200 行截断。process poll与process log会区分因聚合保留上限被丢弃的输出和仅因 pending 缓冲或保留尾部而被省略的输出。被丢弃的输出不可恢复分页日志只能检查保留的部分。源码中appendOutputbash-process-registry.ts在超限时置位truncated/pendingOutputDropped并截断聚合缓冲。poll的timeout参数最多等待相应毫秒数后返回超过 30000 的值被钳制为 30000。轮询用于即时查看状态不是等待循环调度。工作要稍后发生请用 cron。Code Mode 下的表现在 Code Mode 中process直接返回其结构化详情。对action: logoutput包含请求的日志页含分页、保留与输入恢复提示。失败的 process 动作会在status: failed旁边附带error消息让 Agent 能自行选择下一步动作。实用示例运行一个长任务稍后再轮询{ tool: exec, command: sleep 5 echo done, yieldMs: 1000 }{ tool: process, action: poll, sessionId: id }在向交互式会话发送输入前先检查它{ tool: process, action: log, sessionId: id }立即在后台启动{ tool: exec, command: npm run build, background: true }发送 stdin{ tool: process, action: write, sessionId: id, data: y\n }向 PTY 会话发送按键{ tool: process, action: send-keys, sessionId: id, keys: [C-c] }提交当前行{ tool: process, action: submit, sessionId: id }粘贴字面文本{ tool: process, action: paste, sessionId: id, text: line1\nline2\n }相关文档exec 工具exec 审批沙箱化exec 注册表实现exec 工具运行时【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenClaw 后台进程管理：exec 与 process 工具的实现机制与实战指南
OpenClaw 后台进程管理exec 与 process 工具的实现机制与实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 通过exec工具执行 Shell 命令并用内存中的进程注册表承载长时任务process工具则负责对这些后台会话进行轮询、交互与清理。本文完整梳理 exec/process 两个工具的全部参数、环境变量与配置项、Worker 环境下的生命周期规则以及子进程桥接的底层清理机制并结合 OpenClaw 源码中的进程注册表实现帮助你在调试长时任务、管理交互式 CLI 会话时做到心中有数。exec 工具参数与执行行为参数说明参数说明command必填。要执行的 Shell 命令。workdir工作目录省略时使用默认 cwd。env为该命令附加的环境变量。yieldMs等待多少毫秒后转入后台默认 10000。background立即在后台运行。timeoutSeconds超时秒数默认取tools.exec.timeoutSeconds到期即杀进程。对单次调用传timeoutSeconds: 0可禁用该次调用的 exec 进程超时。pty可用时在伪终端中运行适用于需要 TTY 的 CLI、编码类 Agent。elevated当 elevated 模式启用/允许时在沙箱外运行默认走gateway当 exec 目标为node时走node。hostExec 目标auto、sandbox、gateway或node。nodeNode id/name与host: node搭配使用。从源码结构看host的解析遵循单次调用覆盖 → 会话级execHost→ Agent 配置 → 全局tools.exec.host→ 默认auto的优先级链见 exec-defaults.ts。默认超时 1800 秒在 bash-tools.exec-run.ts 中确认defaults.timeoutSec缺省或为 0 时回落到 1800。执行行为前台运行会直接返回保留的输出并显式告知此前输出是否超过了总量上限aggregate cap。当进程被转入后台显式background或yieldMs超时触发时工具返回status: runningsessionId和一段简短的输出尾部。被后台化的调用以及走yieldMs的调用会继承tools.exec.timeoutSeconds除非调用显式传了timeoutSeconds。返回后台会话 ID 并不会停止进程超时。要在 gateway 或沙箱内运行持久化服务应使用background: true搭配timeoutSeconds: 0结束后再用process的kill动作停止它。宿主与 Worker 的生命周期限制仍然生效。输出会驻留在内存中直到达到每会话的聚合上限或被轮询/清除。已结束finished会话在其配置的 TTL 到期后过期TTL 从完成时刻起算。每个 exec 在被接纳admit时捕获当时所属 Agent 的保留期设置用其他 Agent 的 process 工具不会改变既有结果的寿命。注册表最多保留 50 个已结束会话、共 2,000,000 字符的保留输出超限后按最旧记录优先逐出最新的已完成会话即使单条记录超出全局上限也保留其经过截断的每会话聚合输出。这些常量在源码中可以直接找到bash-process-registry.ts 中定义了MAX_FINISHED_SESSION_COUNT 50、MAX_FINISHED_SESSION_OUTPUT_CHARS 2_000_000、DEFAULT_JOB_TTL_MS 30 * 60 * 100030 分钟钳制在 1 分钟到 3 小时之间并有配套的测试 bash-process-registry.test.ts。如果process工具被禁用disallowedexec将同步运行并忽略yieldMs/background。源码中对应 bash-tools.exec-run.ts 的foregroundFallbackWarning逻辑allowBackground为 false 时返回continuation options are unavailable; running synchronously警告。派生的 exec 命令会收到OPENCLAW_SHELLexec环境变量供上下文感知的 shell/profile 规则使用。对于现在就要开始的长时工作启动一次然后在命令产生输出或失败时依赖自动完成唤醒automatic completion wake若已启用。如果自动完成唤醒不可用或你需要对一个干净退出且无输出的命令确认静默成功用process轮询。不要用sleep循环或重复轮询来模拟提醒或延迟跟进——未来的工作交给 cron。环境变量覆盖变量效果OPENCLAW_BASH_YIELD_MS后台化前的默认让出时间ms。默认 10000钳制范围 10–120000。OPENCLAW_BASH_MAX_OUTPUT_CHARS内存中聚合输出的字符上限。默认 200000钳制范围 1000–200000。OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS每个 stdout/stderr 流的待处理输出上限。默认 30000钳制范围 1000–200000且受聚合上限约束。OPENCLAW_BASH_JOB_TTL_MS已结束会话的 TTLms限制在 1 分钟到 3 小时之间。OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS可写后台会话被标记为可能在等待输入之前的空闲输出阈值。默认 15000。源码印证yield 钳制范围在 bash-tools.exec-run.ts 中以clampWithDefault(..., 10_000, 10, 120_000)落实同时兼容旧变量名PI_BASH_YIELD_MSpending 输出默认值DEFAULT_PENDING_OUTPUT_CHARS 30_000与 TTL 钳制函数clampTtl在 bash-process-registry.ts 中。配置项优先于环境变量配置键默认值效果tools.exec.backgroundMs10000等价于OPENCLAW_BASH_YIELD_MS。tools.exec.timeoutSeconds1800每次调用的默认超时。tools.exec.cleanupMs1800000等价于OPENCLAW_BASH_JOB_TTL_MS。tools.exec.notifyOnExittrue后台 exec 退出时入队一个系统事件并请求心跳。tools.exec.notifyOnExitEmptySuccessfalse对成功但无输出的后台运行也入队完成事件。notifyOnExit的解析逻辑见 bash-tools.exec-run.ts仅当显式设为false才关闭。Worker 环境下的后台进程在配对节点paired-node或 node 承载的云端 Worker 上后台进程归属于会话所在的环境结束或取消当前回合turn不会终止已后台化的命令同一环境的后续回合可以用process轮询、发送输入或停止它们前台命令在回合被取消时仍会停止。保留的 Worker 占用一个 node worker 槽位复用它不需要额外槽位。若命令在两个回合之间完成其保留输出对下一个回合仍然可用受常规进程输出上限与 TTL 约束。当一个回合结束时没有存活的后台命令Worker 即退出。迁移或退役环境、替换其归属、或停止节点都会连带停止其进程。进程句柄无法跨越 Worker 或节点重启存活。若节点的配对被吊销或其提供者不再识别该租约lease会话放置会失败。物理清理可能保持 pending直到 OpenClaw 确认该 Worker 确实已停止未确认的停止不会释放其归属记录。Worker 完成目前不会自动唤醒 Gateway 会话请在后续回合用process poll检查结果。关闭 portal 关闭的是它的代理proxy不是开发服务器停止服务器要用process kill。子进程桥接Child Process Bridging在 exec/process 工具之外派生长时子进程时CLI 重启动、gateway 辅助进程应挂接子进程桥接助手使终止信号能够转发、监听器在退出/关闭时解绑。这避免了 systemd 下的孤儿进程并保持跨平台关闭行为一致。关于清理语义文档给出了几条值得注意的保证被监管命令的超时也覆盖启动阶段包括被阻塞的私有输入private-input投递超时结果可能在清理仍在进行时返回。作用域退役与 Gateway 关闭会单独等待清理责任人cleanup owner当该责任人报告不确定uncertainty时按失败上报而不是把超时当作命令已停止的证明。对于归属的 POSIX 进程组清理会等待操作系统在优雅关闭后确认进程组消失。仅命令完成或输出管道关闭并不足以说明其后代进程已停止没有确认清理的强制终止仍保持不确定状态。本地 TUI 的 shell 关闭对自己的命令使用同一个清理责任人。一次性工具的清理会把配置的沙箱运行时保持在 session、agent 或 shared 生命周期上并加入该命令的本地命令传输与后端清理它不会停止 shared 沙箱也不会声称所有远端后代进程已退出。宿主命令包括来自沙箱化会话的 elevated 命令仍需要进程树process-tree级清理。当宿主命令需要进程树清理时pty请求会在启动原生 PTY 之前回退到子进程路径并上报警告确实需要终端的命令在该回退下可能失败。清理失败保持不确定而不会被报告为干净关闭。process 工具动作与行为动作一览动作效果list列出运行中 已结束的会话。poll抽取drain某会话的新输出同时报告退出状态。log读取聚合输出与输入恢复提示支持offsetlimit。write向 stdin 发送数据data可选eof。send-keys向 PTY 承载的会话发送显式按键令牌或字节。submit向 PTY 承载的会话发送回车/换行。paste发送字面文本可选用 bracketed paste 模式包裹。kill终止一个后台会话。clear从内存中移除一个已结束会话。remove运行中则 kill已结束则 clear。行为细节只有被后台化的会话会被列出/保留——纯内存保存不落盘进程重启后会话丢失。重置或删除会话只会清除它已完成的后台进程其他会话、显式 shared 作用域以及运行中的进程不受影响。对应实现为 bash-process-registry.ts 中按 scope 清除clearFinishedSessionsForScopes。存活的后台会话会阻止协作式宿主挂起cooperative host suspension与安全的 Gateway 重启直到进程责任人确认其实际退出。process remove可能在请求终止后立即隐藏一个运行中的会话挂起与重启的阻塞会持续到退出确认。这一点在 markExited 中体现即使可见性被清除activeExecSessions仍通过hasActiveBackgroundExecSession报告进程活性。会话日志只有在你执行process poll/log且工具结果被记录时才会保存进聊天历史。process按 Agent 作用域隔离只能看到该 Agent 启动的会话。当自动完成唤醒不可用时用poll/log获取状态、日志或完成确认。恢复交互式 CLI 前先执行log使当前转写、stdin 状态与输入等待提示能一起看到。需要输入或干预时使用write/send-keys/submit/paste/kill。process list包含派生出的name命令动词 目标便于快速浏览。process list、poll、log仅当会话的 stdin 仍可写且空闲超过输入等待阈值默认 15000 msOPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS时才报告waitingForInput。process log采用基于行的offset/limit两者都省略时返回最后 200 行并附分页提示只设offset未设limit时从offset返回到末尾不做 200 行截断。process poll与process log会区分因聚合保留上限被丢弃的输出和仅因 pending 缓冲或保留尾部而被省略的输出。被丢弃的输出不可恢复分页日志只能检查保留的部分。源码中appendOutputbash-process-registry.ts在超限时置位truncated/pendingOutputDropped并截断聚合缓冲。poll的timeout参数最多等待相应毫秒数后返回超过 30000 的值被钳制为 30000。轮询用于即时查看状态不是等待循环调度。工作要稍后发生请用 cron。Code Mode 下的表现在 Code Mode 中process直接返回其结构化详情。对action: logoutput包含请求的日志页含分页、保留与输入恢复提示。失败的 process 动作会在status: failed旁边附带error消息让 Agent 能自行选择下一步动作。实用示例运行一个长任务稍后再轮询{ tool: exec, command: sleep 5 echo done, yieldMs: 1000 }{ tool: process, action: poll, sessionId: id }在向交互式会话发送输入前先检查它{ tool: process, action: log, sessionId: id }立即在后台启动{ tool: exec, command: npm run build, background: true }发送 stdin{ tool: process, action: write, sessionId: id, data: y\n }向 PTY 会话发送按键{ tool: process, action: send-keys, sessionId: id, keys: [C-c] }提交当前行{ tool: process, action: submit, sessionId: id }粘贴字面文本{ tool: process, action: paste, sessionId: id, text: line1\nline2\n }相关文档exec 工具exec 审批沙箱化exec 注册表实现exec 工具运行时【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![Daily Briefing | [Day, Month Date]](http://pic.xiahunao.cn/yaotu/Daily Briefing | [Day, Month Date])
