后台进程与 exec/process 工具

OpenClaw 通过 exec 工具执行 shell 命令，通过 process 工具管理后台会话。

exec 工具核心参数

参数	说明
command	必填，执行命令
yieldMs	超时后自动转后台，默认 10000ms
background	立即转后台
timeout	进程超时秒数，0 表示禁用
elevated	在沙箱外运行（需启用 elevated 模式）
pty	需要真实 TTY 时设为 true

行为要点：

• 前台运行直接返回输出；后台运行返回 status: "running" + sessionId
• 后台会话输出保存在内存中，直到被 poll 或 clear
• 若 process 工具被禁用，exec 同步运行，忽略 yieldMs/background
• 子进程环境变量 OPENCLAW_SHELL=exec

exec 配置项（openclaw.json）

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
    }
  }
}

process 工具操作

操作	说明
list	列出运行中和已完成的会话
poll	获取新输出（含退出状态）
log	读取聚合输出，支持 offset/limit
write	发送 stdin 数据
send-keys	向 PTY 会话发送按键
submit	发送 Enter/回车
paste	发送文字（支持 bracketed paste）
kill	终止后台会话
clear	从内存移除已完成会话
remove	运行中则 kill，已完成则 clear

注意事项：

• 会话仅在进程重启前有效，无磁盘持久化
• process 按 agent 隔离，只能看到本 agent 启动的会话
• process log 默认返回最后 200 行

常用示例

// 后台运行并轮询
{ "tool": "exec", "command": "npm run build", "background": true }
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
 
// 发送 stdin
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
 
// 发送 Ctrl+C
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

相关链接

• gateway-sandbox-policy — 沙箱与工具策略
• gateway-troubleshooting — 故障排查