OpenClaw 后台执行与进程管理指南

 

在 AI Agent 与系统深度交互的场景中，处理长时间任务（如代码编译、数据流水线、构建脚本）是核心需求。OpenClaw 通过 exec（执行入口）和 process（进程管理）两大工具，提供了一套完整的后台任务生命周期管理方案。

核心设计理念

• 前台即时响应：短任务直接返回结果。
• 后台持久化管理：长任务自动转入内存会话，避免超时中断。
• 严格会话隔离：Agent 仅能管理自己启动的进程。
• 自动资源回收：过期会话自动清理，防止内存泄漏。

---

1. exec 工具：执行入口与控制

exec 是所有命令执行的起点，支持丰富的参数以控制执行行为。

核心参数详解

三种执行模式

模式 A：前台同步执行（默认）

适合快速返回结果的命令（如 ls, cat, grep）。

{ "tool": "exec", "command": "ls -la" }
// 响应：直接包含完整 stdout/stderr

模式 B：智能自动后台化

当任务执行时间超过 yieldMs（默认 10 秒），系统自动将其转为后台任务。

{ "tool": "exec", "command": "npm run build" }
// 响应：
// {
//   "status": "running",
//   "sessionId": "exec_1741852800_abc123",
//   "tail": "任务开始...\n依赖安装中..." 
// }

模式 C：强制立即后台化

对于已知耗时的任务（如 Docker 构建），显式声明 background: true。

{ 
  "tool": "exec", 
  "command": "docker build -t myapp .", 
  "background": true 
}

智能环境感知

OpenClaw 会自动注入 OPENCLAW_SHELL=exec 环境变量，允许脚本根据上下文调整行为：

# .bashrc 示例
if [ "$OPENCLAW_SHELL" = "exec" ]; then
    PS1='> '  # 简化提示符，减少输出噪音
    export CI=true
else
    PS1='\u@\h:\w\$ '
fi

---

2. process 工具：全生命周期管理

一旦任务进入后台，使用 process 工具进行监控、交互和控制。

 核心操作速查

使用示例

1. 轮询实时进度

{ 
  "tool": "process", 
  "action": "poll", 
  "sessionId": "exec_1741852800_abc123" 
}
// 返回：{ "status": "running", "output": "编译进度 50%...", "exitCode": null }

2. 分页读取大日志
避免一次性加载过大日志，使用分页读取：

// 读取第 100 行开始的 100 行
{ 
  "tool": "process", 
  "action": "log", 
  "sessionId": "exec_1741852800_abc123", 
  "offset": 100, 
  "limit": 100 
}

3. 交互式输入
向运行中的进程（如 MySQL CLI）发送指令：

// 发送密码
{ "tool": "process", "action": "write", "sessionId": "...", "data": "mypassword\n" }
// 发送结束符
{ "tool": "process", "action": "write", "sessionId": "...", "eof": true }

3. 典型应用场景

场景一：自动化构建监控

# 1. 启动构建
res = agent.exec("npm run build", background=True)
sid = res.session_id

# 2. 轮询直到完成
while True:
    status = agent.process_poll(sid)
    print(status.output) # 仅打印新增输出
    if status.status == "finished":
        print(f"完成，退出码：{status.exit_code}")
        break
    time.sleep(5)

# 3. 归档完整日志
full_log = agent.process_log(sid)

场景二：并行任务编排

同时启动前端、后端构建及测试，互不阻塞：

tasks = [
    agent.exec("npm run build:fe", background=True),
    agent.exec("npm run build:be", background=True),
    agent.exec("npm test", background=True)
]

# 等待所有任务完成
for task in tasks:
    while agent.process_poll(task.session_id).status != "finished":
        time.sleep(2)

场景三：交互式 CLI 操作

# 启动 Python REPL
session = agent.exec("python", pty=True, background=True)

# 发送代码
agent.process_write(session.session_id, "print('Hello OpenClaw')\n")
# 获取输出
print(agent.process_poll(session.session_id).output)

4. 配置调优与资源控制

在 openclaw.json 中精细化控制执行行为：

{
  tools: {
    exec: {
      //  时间与阈值
      backgroundMs: 10000,       // 自动转后台阈值 (ms)
      timeoutSec: 1800,          // 全局超时 (s)
      cleanupMs: 1800000,        // 已完成会话保留时间 (ms)
      
      // 通知策略
      notifyOnExit: true,        // 退出时通知
      notifyOnExitEmptySuccess: false, 
      
      // 资源限制
      maxOutputChars: 100000,    // 单会话内存保留上限 (字符)
    }
  },
  agents: {
    list: [{
      id: "build-agent",
      tools: {
        exec: {
          maxBackgroundSessions: 5, // 限制最大并发后台数
          defaultTimeout: 3600      // 覆盖全局超时
        }
      }
    }]
  }
}

环境变量覆盖

临时调整无需重启配置：

• PI_BASH_YIELD_MS: 覆盖自动后台化阈值
• PI_BASH_MAX_OUTPUT_CHARS: 限制输出缓冲区大小
• PI_BASH_JOB_TTL_MS: 控制已完成会话的存活时间 (1min - 3h)

5. 安全与稳定性最佳实践

安全加固

1. 沙箱隔离：始终在沙箱中运行不可信代码。

   { tools: { exec: { host: "sandbox", security: "ask" } } }
   

2. 审计日志：开启敏感信息脱敏。

   { logging: { redactSensitive: "tools", execOutputLimit: 10000 } }
   

3. 权限最小化：默认禁用 elevated (提权) 模式，仅在必要时显式开启。

推荐做法 (Do's)

• 显式声明：对长任务明确设置 background: true。
• 增量轮询：使用 poll 而非反复调用 log 获取全量数据。
• 及时清理：任务完成后调用 clear 释放内存。
• 命名规范：利用 process list 中的名称字段快速定位任务。

 避免做法 (Don'ts)

• 忽视僵尸进程：长期运行的任务若不监控会耗尽资源。
• 全量读取大文件：避免对 GB 级日志使用无参数的 log。
• 依赖持久化：网关重启会导致所有后台会话丢失，设计时需考虑断点续传或状态外存。
• 跨 Agent 共享：不要尝试在不同 Agent 间共享进程 ID，这是被隔离的。

6. 底层机制：子进程桥接

当 OpenClaw 运行在 systemd 等守护进程管理器下时，内置的子进程桥接助手确保：

• 信号（SIGTERM/SIGINT）正确转发给子进程树。
• 避免产生孤儿进程。
• 监听器在退出时优雅分离。

这保证了即使在复杂的系统服务环境下，进程生命周期也能得到一致且可靠的管理。

结语

OpenClaw 的 exec + process 组合拳，让 AI Agent 具备了企业级的任务调度能力。

• 短期任务：同步执行，即时反馈。
• 长期任务：异步托管，可控可查。
• 复杂交互：stdin/stdout 双向流通。

记住核心原则：前台求快，后台求稳，会话隔离，用完即清。合理利用这套机制，你的 AI 助手将能优雅地驾驭从简单脚本到复杂流水线的各类系统任务。