Background Exec + Process Tool

OpenClaw chạy các lệnh shell thông qua tool exec và giữ các tác vụ chạy lâu trong bộ nhớ. Tool process quản lý các session nền đó.

exec tool

Các tham số chính:

  • command (bắt buộc)
  • yieldMs (mặc định 10000): tự động chuyển sang nền sau khoảng thời gian này
  • background (bool): chuyển sang nền ngay lập tức
  • timeout (giây, mặc định 1800): kill process sau khoảng thời gian này
  • elevated (bool): chạy trên host nếu elevated mode được bật/cho phép
  • Cần TTY thật? Set pty: true.
  • workdir, env

Cách hoạt động:

  • Chạy foreground sẽ trả output trực tiếp.
  • Khi chuyển sang nền (tường minh hoặc timeout), tool trả về status: "running" + sessionId và một đoạn tail ngắn.
  • Output được giữ trong bộ nhớ cho đến khi session được poll hoặc clear.
  • Nếu tool process bị cấm, exec chạy đồng bộ và bỏ qua yieldMs/background.

Child process bridging

Khi spawn các child process chạy lâu bên ngoài exec/process tools (ví dụ: CLI respawn hoặc gateway helper), các bạn cần attach child-process bridge helper để termination signal được forward và listener được detach khi exit/error. Điều này tránh các process mồ côi trên systemd và giữ shutdown behavior nhất quán trên các nền tảng.

Environment override:

  • PI_BASH_YIELD_MS: yield mặc định (ms)
  • PI_BASH_MAX_OUTPUT_CHARS: giới hạn output trong bộ nhớ (ký tự)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: giới hạn stdout/stderr pending mỗi stream (ký tự)
  • PI_BASH_JOB_TTL_MS: TTL cho các session đã hoàn thành (ms, giới hạn từ 1 phút đến 3 giờ)

Config (khuyên dùng):

  • tools.exec.backgroundMs (mặc định 10000)
  • tools.exec.timeoutSec (mặc định 1800)
  • tools.exec.cleanupMs (mặc định 1800000)
  • tools.exec.notifyOnExit (mặc định true): đưa system event vào hàng đợi + request heartbeat khi exec nền thoát.

process tool

Các action:

  • list: các session đang chạy + đã hoàn thành
  • poll: lấy output mới cho một session (cũng báo cáo exit status)
  • log: đọc output tổng hợp (hỗ trợ offset + limit)
  • write: gửi stdin (data, eof tùy chọn)
  • kill: terminate một session nền
  • clear: xóa session đã hoàn thành khỏi bộ nhớ
  • remove: kill nếu đang chạy, ngược lại clear nếu đã hoàn thành

Lưu ý:

  • Chỉ các session nền mới được list/lưu trong bộ nhớ.
  • Session bị mất khi process restart (không có disk persistence).
  • Session log chỉ được lưu vào chat history nếu các bạn chạy process poll/log và tool result được ghi lại.
  • process được scope theo agent; nó chỉ thấy các session được khởi tạo bởi agent đó.
  • process list bao gồm name được tạo tự động (command verb + target) để scan nhanh.
  • process log dùng offset/limit theo dòng (bỏ qua offset để lấy N dòng cuối).

Ví dụ

Chạy một tác vụ dài và poll sau:

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
{ "tool": "process", "action": "poll", "sessionId": "<id>" }

Chạy ngay lập tức ở nền:

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

Gửi stdin:

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }