后台 Exec 和进程工具

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

Exec 工具

参数：

行为：

• 前台运行会直接返回输出。
• 转入后台时（显式指定或因 yieldMs 超时），工具会返回 status: "running" + sessionId 以及一小段输出末尾内容。
• 后台运行和 yieldMs 运行会继承 tools.exec.timeoutSeconds，除非调用显式传入 timeout。
• 输出会保留在内存中，直到轮询或清除该会话。
• 如果不允许使用 process 工具，exec 会同步运行并忽略 yieldMs/background。
• 生成的 Exec 命令会接收 OPENCLAW_SHELL=exec，用于支持上下文感知的 shell/配置文件规则。
• 对于现在开始的长时间运行任务：只启动一次，并在命令产生输出或失败后依赖自动完成唤醒（启用时）。
• 如果自动完成唤醒不可用，或者需要确认一个无输出且正常退出的命令是否静默成功，请使用 process 进行轮询。
• 不要使用 sleep 循环或重复轮询来模拟提醒或延迟跟进——未来要执行的工作请使用 cron。

环境变量覆盖项

配置（优先于环境变量覆盖项）

子进程桥接

在 Exec/Process 工具之外生成长时间运行的子进程时（CLI 重新生成、Gateway 网关辅助程序），请附加子进程桥接辅助程序，以便转发终止信号，并在退出/出错时移除监听器。这样可以避免 systemd 上出现孤立进程，并使各平台的关闭行为保持一致。

Process 工具

操作：

说明：

• 仅列出/保留后台会话——只保存在内存中，不会写入磁盘。进程重启时会话将丢失。
• 在进程所有者确认后台会话已实际退出之前，仍在运行的后台会话会阻止协作式主机挂起和安全重启 Gateway 网关。
• process remove 可以在请求终止后立即隐藏正在运行的会话；在确认退出之前，挂起和重启仍会被阻止。
• 只有运行 process poll/log 且工具结果被记录时，会话日志才会保存到聊天历史记录中。
• process 的作用域按智能体划分；它只能看到由该智能体启动的会话。
• 当自动完成唤醒不可用时，使用 poll/log 获取状态、日志或完成确认。
• 恢复交互式 CLI 前，请使用 log，以便同时查看当前记录、stdin 状态和输入等待提示。
• 需要输入或干预时，请使用 write/send-keys/submit/paste/kill。
• process list 包含派生的 name（命令动词 + 目标），便于快速浏览。
• 只有当会话仍有可写的 stdin，并且空闲时间超过输入等待阈值（默认 15000 ms，OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS）时，process list、poll 和 log 才会报告 waitingForInput。
• process log 使用基于行的 offset/limit。两者都省略时，它会返回最后 200 行以及分页提示。设置 offset 且未设置 limit 时，它会返回从 offset 到末尾的内容（不限制为 200 行）。
• poll 的 timeout 在返回前最多等待指定的毫秒数；超过 30000 的值会被限制为 30000。
• 轮询用于按需获取状态，而不是安排等待循环。如果工作应在以后执行，请使用 cron。

示例

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

{ "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 审批