Thực thi nền và công cụ tiến trình

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

​

Công cụ exec

Tham số:

Tham số	Mô tả
command	Bắt buộc. Lệnh shell cần chạy.
workdir	Thư mục làm việc; bỏ qua để sử dụng cwd mặc định.
env	Các biến môi trường bổ sung cho lệnh.
yieldMs	Số mili giây chờ trước khi chuyển sang chạy nền (mặc định là 10000).
background	Chạy nền ngay lập tức.
timeout	Thời gian chờ tính bằng giây (mặc định là tools.exec.timeoutSec); kết thúc tiến trình khi hết hạn. Đặt timeout: 0 để tắt thời gian chờ của tiến trình exec cho lần gọi đó.
pty	Chạy trong thiết bị đầu cuối giả khi có thể (các CLI yêu cầu TTY, tác nhân lập trình).
elevated	Chạy bên ngoài sandbox nếu chế độ nâng cao được bật/cho phép (mặc định là gateway, hoặc node khi đích exec là node).
host	Đích exec: auto, sandbox, gateway hoặc node.
node	ID/tên Node, được sử dụng với host: "node".

Hành vi:

• Các lần chạy ở chế độ tiền cảnh trả về đầu ra trực tiếp.
• Khi được chuyển sang chạy nền (rõ ràng hoặc do hết thời gian yieldMs), công cụ trả về status: "running" + sessionId và một đoạn ngắn ở cuối đầu ra.
• Các lần chạy nền và chạy với yieldMs kế thừa tools.exec.timeoutSec, trừ khi lần gọi truyền timeout rõ ràng.
• Đầu ra được giữ trong bộ nhớ cho đến khi phiên được thăm dò hoặc xóa.
• Nếu công cụ process không được phép, exec chạy đồng bộ và bỏ qua yieldMs/background.
• Các lệnh exec được khởi chạy nhận OPENCLAW_SHELL=exec để áp dụng các quy tắc shell/hồ sơ có nhận biết ngữ cảnh.
• Đối với công việc chạy lâu bắt đầu ngay bây giờ: chỉ khởi động một lần và dựa vào cơ chế đánh thức tự động khi hoàn tất (nếu được bật) sau khi lệnh tạo đầu ra hoặc thất bại.
• Nếu cơ chế đánh thức tự động khi hoàn tất không khả dụng, hoặc bạn cần xác nhận thành công im lặng cho một lệnh thoát bình thường mà không có đầu ra, hãy thăm dò bằng process.
• Không mô phỏng lời nhắc hoặc thao tác theo dõi trì hoãn bằng vòng lặp sleep hay thăm dò lặp lại — hãy dùng Cron cho công việc trong tương lai.

​

Ghi đè bằng biến môi trường

Biến	Tác dụng
OPENCLAW_BASH_YIELD_MS	Thời gian chờ mặc định trước khi chuyển sang chạy nền (ms). Mặc định là 10000, được giới hạn trong khoảng 10-120000.
OPENCLAW_BASH_MAX_OUTPUT_CHARS	Giới hạn đầu ra trong bộ nhớ (ký tự).
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS	Giới hạn stdout/stderr đang chờ cho mỗi luồng (ký tự).
OPENCLAW_BASH_JOB_TTL_MS	TTL cho các phiên đã hoàn tất (ms), được giới hạn trong khoảng 1 phút-3 giờ.
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS	Ngưỡng không có đầu ra trước khi các phiên chạy nền có thể ghi được đánh dấu là có khả năng đang chờ dữ liệu đầu vào. Mặc định là 15000.

​

Cấu hình (được ưu tiên hơn ghi đè bằng biến môi trường)

Khóa	Mặc định	Tác dụng
tools.exec.backgroundMs	10000	Giống OPENCLAW_BASH_YIELD_MS.
tools.exec.timeoutSec	1800	Thời gian chờ mặc định cho mỗi lần gọi.
tools.exec.cleanupMs	1800000	Giống OPENCLAW_BASH_JOB_TTL_MS.
tools.exec.notifyOnExit	true	Đưa một sự kiện hệ thống vào hàng đợi + yêu cầu Heartbeat khi một tiến trình exec chạy nền thoát.
tools.exec.notifyOnExitEmptySuccess	false	Đồng thời đưa các sự kiện hoàn tất vào hàng đợi cho những lần chạy nền thành công nhưng không có đầu ra.

​

Cầu nối tiến trình con

Khi khởi chạy các tiến trình con chạy lâu bên ngoài công cụ exec/process (CLI tự khởi chạy lại, trình trợ giúp Gateway), hãy gắn trình trợ giúp cầu nối tiến trình con để chuyển tiếp tín hiệu kết thúc và tháo các trình lắng nghe khi thoát/gặp lỗi. Điều này tránh các tiến trình mồ côi trên systemd và duy trì quy trình tắt nhất quán trên các nền tảng.

​

Công cụ process

Thao tác:

Thao tác	Tác dụng
list	Các phiên đang chạy + đã hoàn tất.
poll	Đọc và loại khỏi bộ đệm đầu ra mới của một phiên (đồng thời báo cáo trạng thái thoát).
log	Đọc đầu ra tổng hợp và gợi ý khôi phục dữ liệu đầu vào. Hỗ trợ offset + limit.
write	Gửi stdin (data, eof tùy chọn).
send-keys	Gửi các mã phím hoặc byte cụ thể tới phiên sử dụng PTY.
submit	Gửi Enter/ký tự xuống dòng tới phiên sử dụng PTY.
paste	Gửi văn bản nguyên dạng, có thể được bao trong chế độ dán có dấu ngoặc.
kill	Kết thúc một phiên chạy nền.
clear	Xóa một phiên đã hoàn tất khỏi bộ nhớ.
remove	Kết thúc nếu đang chạy, nếu không thì xóa nếu đã hoàn tất.

Lưu ý:

• Chỉ các phiên chạy nền mới được liệt kê/lưu giữ — chỉ trong bộ nhớ, không phải trên đĩa. Các phiên sẽ mất khi tiến trình khởi động lại.
• Một phiên chạy nền còn hoạt động sẽ chặn việc tạm ngưng máy chủ theo cơ chế hợp tác và khởi động lại Gateway an toàn cho đến khi chủ sở hữu tiến trình xác nhận tiến trình thực sự đã thoát.
• process remove có thể ẩn ngay một phiên đang chạy sau khi yêu cầu kết thúc; việc tạm ngưng và khởi động lại vẫn bị chặn cho đến khi xác nhận tiến trình đã thoát.
• Nhật ký phiên chỉ được lưu vào lịch sử trò chuyện nếu bạn chạy process poll/log và kết quả công cụ được ghi lại.
• process có phạm vi theo từng tác nhân; nó chỉ nhìn thấy các phiên do tác nhân đó khởi động.
• Dùng poll/log để xem trạng thái, nhật ký hoặc xác nhận hoàn tất khi cơ chế đánh thức tự động khi hoàn tất không khả dụng.
• Dùng log trước khi khôi phục một CLI tương tác để có thể xem đồng thời bản ghi hiện tại, trạng thái stdin và gợi ý chờ dữ liệu đầu vào.
• Dùng write/send-keys/submit/paste/kill khi bạn cần nhập dữ liệu hoặc can thiệp.
• process list bao gồm một name được suy ra (động từ lệnh + đích) để quét nhanh.
• process list, poll và log chỉ báo cáo waitingForInput khi phiên vẫn có stdin có thể ghi và đã không hoạt động lâu hơn ngưỡng chờ dữ liệu đầu vào (mặc định là 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
• process log sử dụng offset/limit theo dòng. Khi cả hai đều bị bỏ qua, nó trả về 200 dòng cuối cùng cùng gợi ý phân trang. Khi đặt offset nhưng không đặt limit, nó trả về từ offset đến cuối (không bị giới hạn ở 200 dòng).
• timeout của poll chờ tối đa số mili giây đó trước khi trả về; các giá trị lớn hơn 30000 được giới hạn ở 30000.
• Việc thăm dò dùng để kiểm tra trạng thái theo yêu cầu, không phải để lập lịch vòng lặp chờ. Nếu công việc cần diễn ra sau này, hãy dùng Cron.

​

Ví dụ

Chạy một tác vụ dài và thăm dò sau:

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

{ "tool": "process", "action": "poll", "sessionId": "<id>" }

Kiểm tra một phiên tương tác trước khi gửi dữ liệu đầu vào:

{ "tool": "process", "action": "log", "sessionId": "<id>" }

Bắt đầu chạy nền ngay lập tức:

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

Gửi stdin:

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

Gửi các phím PTY:

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

Gửi dòng hiện tại:

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

Dán văn bản nguyên dạng:

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​

Liên quan

• Công cụ Exec
• Phê duyệt Exec