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

​
exec 工具

参数：
参数描述
command必填。要运行的 shell 命令。
workdir工作目录；省略则使用默认 cwd。
env命令的额外环境变量。
yieldMs转入后台前等待的毫秒数（默认 10000）。
background立即在后台运行。
timeout超时时间（秒，默认 tools.exec.timeoutSec）；到期后终止进程。设置 timeout: 0 可为该次调用禁用 exec 进程超时。
pty在可用时通过伪终端运行（需要 TTY 的 CLI、编码智能体）。
elevated如果提升权限模式已启用/允许，则在沙箱外运行（默认是 gateway，或当 exec 目标为 node 时是 node）。
hostExec 目标：auto、sandbox、gateway 或 node。
node节点 ID/名称，与 host: "node" 配合使用。
行为：
  • 前台运行会直接返回输出。
  • 转入后台时（显式指定或通过 yieldMs 超时），该工具会返回 status: "running" + sessionId 和一小段输出尾部。
  • 后台运行和 yieldMs 运行会继承 tools.exec.timeoutSec，除非该调用传入显式 timeout。
  • 输出会保留在内存中，直到会话被轮询或清除。
  • 如果 process 工具被禁用，exec 会同步运行，并忽略 yieldMs/background。
  • 派生的 exec 命令会收到 OPENCLAW_SHELL=exec，用于上下文感知的 shell/profile 规则。
  • 对于现在启动的长时间运行工作：只启动一次，并在命令产生输出或失败后依赖自动完成唤醒（如果已启用）。
  • 如果自动完成唤醒不可用，或者你需要确认一个无输出但干净退出的命令是否静默成功，请用 process 轮询。
  • 不要用 sleep 循环或重复轮询来模拟提醒或延迟跟进 —— 未来工作请使用 cron。

​
Env 覆盖项

变量效果
OPENCLAW_BASH_YIELD_MS转入后台前的默认等待时间（毫秒）。默认 10000，限制在 10-120000。
OPENCLAW_BASH_MAX_OUTPUT_CHARS内存中输出上限（字符）。
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS每个流的待处理 stdout/stderr 上限（字符）。
OPENCLAW_BASH_JOB_TTL_MS已完成会话的 TTL（毫秒），限制为 1 分钟到 3 小时。
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS可写后台会话被标记为可能正在等待输入前的空闲输出阈值。默认 15000。

​
配置（优先于 env 覆盖项）

键默认值效果
tools.exec.backgroundMs10000与 OPENCLAW_BASH_YIELD_MS 相同。
tools.exec.timeoutSec1800默认的每次调用超时时间。
tools.exec.cleanupMs1800000与 OPENCLAW_BASH_JOB_TTL_MS 相同。
tools.exec.notifyOnExittrue后台 exec 退出时，排入系统事件并请求心跳。
tools.exec.notifyOnExitEmptySuccessfalse也为无输出的成功后台运行排入完成事件。

​
子进程桥接

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

​
process 工具

操作：
操作效果
list运行中 + 已完成的会话。
poll排出某个会话的新输出（也会报告退出状态）。
log读取聚合输出和输入恢复提示。支持 offset + limit。
write发送 stdin（data，可选 eof）。
send-keys向 PTY 支持的会话发送显式按键 token 或字节。
submit向 PTY 支持的会话发送 Enter/回车。
paste发送字面文本，可选用 bracketed paste 模式包装。
kill终止后台会话。
clear从内存中移除已完成会话。
remove如果正在运行则终止，否则如果已完成则清除。
说明：
  • 只有后台会话会被列出/持久保留 —— 仅在内存中，不在磁盘上。进程重启后会话会丢失。
  • 只有在运行 process poll/log 且工具结果被记录时，会话日志才会保存到聊天历史中。
  • process 按智能体划定范围；它只能看到该智能体启动的会话。
  • 当自动完成唤醒不可用时，使用 poll/log 获取状态、日志或完成确认。
  • 在恢复交互式 CLI 前使用 log，这样当前转录、stdin 状态和输入等待提示会一起可见。
  • 需要输入或干预时，使用 write/send-keys/submit/paste/kill。
  • process list 包含派生的 name（命令动词 + 目标），便于快速浏览。
  • process list、poll 和 log 仅在会话仍有可写 stdin，且空闲时间超过输入等待阈值（默认 15000 毫秒，OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS）时报告 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" }

​
相关