后台 Exec 与 Process 工具

OpenClaw 通过 exec 工具运行 shell 命令，并将长时间运行的任务保留在内存中。process 工具负责管理这些后台会话。

exec 工具

关键参数：

• command（必填）
• yieldMs（默认 10000）：超过此延迟后自动转为后台运行
• background（布尔值）：立即在后台运行
• timeout（秒，默认 1800）：超时后终止进程
• elevated（布尔值）：如果启用了 elevated 模式，则在主机上运行
• 需要真实 TTY？设置 pty: true
• workdir、env

行为说明：

• 前台运行直接返回输出。
• 当转入后台（显式或超时），工具返回 status: "running" + sessionId 以及一小段输出片段。
• 输出会保留在内存中，直到会话被轮询或清除。
• 如果 process 工具被禁止，exec 将同步运行并忽略 yieldMs/background。
• 启动的 exec 命令会收到 OPENCLAW_SHELL=exec 用于上下文感知的 shell/profile 规则。

子进程桥接

当在 exec/process 工具之外启动长时间运行的子进程时（例如 CLI 重生或 gateway 辅助进程），请附加子进程桥接帮助程序，以确保终止信号被转发，并在退出/错误时分离监听器。这样可以避免在 systemd 上产生孤立进程，并保持跨平台的一致关闭行为。

环境变量覆盖：

• PI_BASH_YIELD_MS：默认 yield 时间（毫秒）
• PI_BASH_MAX_OUTPUT_CHARS：内存输出上限（字符数）
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS：每个流的待处理 stdout/stderr 上限（字符数）
• PI_BASH_JOB_TTL_MS：已完成会话的 TTL（毫秒，限制在 1 分钟到 3 小时之间）

配置（推荐）：

• tools.exec.backgroundMs（默认 10000）
• tools.exec.timeoutSec（默认 1800）
• tools.exec.cleanupMs（默认 1800000）
• tools.exec.notifyOnExit（默认 true）：当后台 exec 退出时，将系统事件加入队列并请求心跳。
• tools.exec.notifyOnExitEmptySuccess（默认 false）：为 true 时，对无输出的成功后台运行也触发完成事件。

process 工具

操作说明：

• list：列出运行中和已完成的会话
• poll：抓取会话的新输出（同时报告退出状态）
• log：读取聚合输出（支持 offset + limit）
• write：发送 stdin（data，可选 eof）
• kill：终止后台会话
• clear：从内存中移除已完成的会话
• remove：如果运行中则 kill，如果已完成则 clear

注意事项：

• 只有后台会话才会被列出并保留在内存中。
• 进程重启后会话丢失（不持久化到磁盘）。
• 会话日志只有在你运行 process poll/log 且工具结果被记录时，才会保存到聊天历史。
• process 的范围是每个 agent；它只能看到该 agent 启动的会话。
• process list 包含一个派生的 name（命令动词 + 目标）以便快速扫描。
• process log 使用基于行的 offset/limit。
• 当 offset 和 limit 都省略时，返回最后 200 行并附带分页提示。
• 当提供了 offset 但省略 limit 时，从 offset 返回到末尾（不限制到 200 行）。

示例

运行长时间任务并稍后轮询：

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

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

立即在后台启动：

{ "tool": "exec", "command": "npm run build", "background": true }

发送 stdin：

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

---

小贴士：用"养龙虾"跑 build？把它扔后台吧——"background": true 一键解放你的终端，等龙虾干完活再来收结果。