6.15 后台执行

OpenClaw 提供了 exec 和 process 工具来执行 Shell 命令和管理后台会话。本文档介绍如何使用这些工具进行后台任务执行和进程管理。

exec 工具

exec 工具用于执行 Shell 命令，支持前台和后台两种执行模式。

基本参数

参数	类型	说明	默认值
command	string	要执行的命令	必填
yieldMs	number	前台执行的超时时间（毫秒）	10000
background	boolean	是否在后台执行	false
timeout	number	命令执行超时时间（秒）	1800
elevated	boolean	是否需要提升权限	false
pty	boolean	是否使用伪终端	false
workdir	string	工作目录	当前目录
env	object	环境变量	{}

前台执行

前台执行会直接返回命令输出：

{
  "tool": "exec",
  "command": "ls -la",
  "yieldMs": 5000
}

后台执行

后台执行会返回会话 ID 和初始输出：

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

返回示例：

{
  "status": "running",
  "sessionId": "abc123",
  "output": "Building..."
}

长时间运行的命令

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

process 工具

process 工具用于管理后台会话，支持多种操作。

会话操作

列出所有会话

{
  "tool": "process",
  "action": "list"
}

轮询会话状态

{
  "tool": "process",
  "action": "poll",
  "sessionId": "abc123"
}

获取会话日志

支持分页读取日志：

{
  "tool": "process",
  "action": "log",
  "sessionId": "abc123",
  "offset": 0,
  "limit": 100
}

向会话写入数据

向交互式进程的标准输入写入数据：

{
  "tool": "process",
  "action": "write",
  "sessionId": "abc123",
  "data": "y\n"
}

终止会话

{
  "tool": "process",
  "action": "kill",
  "sessionId": "abc123"
}

清除会话输出

{
  "tool": "process",
  "action": "clear",
  "sessionId": "abc123"
}

移除会话

{
  "tool": "process",
  "action": "remove",
  "sessionId": "abc123"
}

环境变量配置

可以通过环境变量调整后台执行行为：

环境变量	说明
PI_BASH_YIELD_MS	默认的 yieldMs 值
PI_BASH_MAX_OUTPUT_CHARS	最大输出字符数
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS	待处理输出的最大字符数
PI_BASH_JOB_TTL_MS	后台任务的生存时间

配置选项

在配置文件中可以设置以下选项：

{
  "tools": {
    "exec": {
      "backgroundMs": 10000,
      "timeoutSec": 1800,
      "cleanupMs": 300000,
      "notifyOnExit": true
    }
  }
}

子进程桥接

OpenClaw 确保信号转发和优雅关闭：

• 自动转发 SIGINT、SIGTERM 等信号到子进程
• 网关关闭时清理所有后台进程
• 支持进程组管理

会话管理特性

• 内存存储：只有后台会话保存在内存中，无磁盘持久化
• 代理作用域：会话按代理隔离
• 自动命名：list 操作显示派生的会话名称
• 行级日志：log 操作使用基于行的偏移量和限制

使用注意事项

完整示例

执行构建任务并监控进度：

# 1. 启动后台构建
{
  "tool": "exec",
  "command": "npm run build",
  "background": true,
  "workdir": "/path/to/project"
}

# 2. 轮询构建状态
{
  "tool": "process",
  "action": "poll",
  "sessionId": "build-session-123"
}

# 3. 获取构建日志
{
  "tool": "process",
  "action": "log",
  "sessionId": "build-session-123",
  "offset": 0,
  "limit": 50
}

# 4. 构建完成后清理会话
{
  "tool": "process",
  "action": "remove",
  "sessionId": "build-session-123"
}