Langsung ke konten utama
OpenClaw menjalankan perintah shell melalui alat exec dan menyimpan tugas berjalan lama di memori. Alat process mengelola sesi latar belakang tersebut.

​
alat exec

Parameter utama:
  • command (wajib)
  • yieldMs (default 10000): otomatis berjalan di latar belakang setelah penundaan ini
  • background (bool): langsung berjalan di latar belakang
  • timeout (detik, default tools.exec.timeoutSec): hentikan proses setelah batas waktu ini; atur timeout: 0 hanya untuk menonaktifkan batas waktu proses exec untuk panggilan tersebut
  • elevated (bool): jalankan di luar sandbox jika mode elevated diaktifkan/diizinkan (gateway secara default, atau node ketika target exec adalah node)
  • Perlu TTY sungguhan? Atur pty: true.
  • workdir, env
Perilaku:
  • Proses foreground mengembalikan output secara langsung.
  • Saat dijalankan di latar belakang (eksplisit atau karena batas waktu), alat mengembalikan status: "running" + sessionId dan tail singkat.
  • Proses latar belakang dan proses yieldMs mewarisi tools.exec.timeoutSec kecuali panggilan menyediakan timeout eksplisit.
  • Output disimpan di memori sampai sesi di-poll atau dibersihkan.
  • Jika alat process tidak diizinkan, exec berjalan sinkron dan mengabaikan yieldMs/background.
  • Perintah exec yang dibuat menerima OPENCLAW_SHELL=exec untuk aturan shell/profil yang sadar konteks.
  • Untuk pekerjaan berjalan lama yang dimulai sekarang, mulai sekali dan andalkan pemicu bangun penyelesaian otomatis saat diaktifkan dan perintah mengeluarkan output atau gagal.
  • Jika pemicu bangun penyelesaian otomatis tidak tersedia, atau Anda memerlukan konfirmasi keberhasilan senyap untuk perintah yang selesai bersih tanpa output, gunakan process untuk mengonfirmasi penyelesaian.
  • Jangan meniru pengingat atau tindak lanjut tertunda dengan loop sleep atau polling berulang; gunakan cron untuk pekerjaan mendatang.

​
Penjembatanan proses anak

Saat membuat proses anak berjalan lama di luar alat exec/process (misalnya, respawn CLI atau helper gateway), pasang helper jembatan proses anak agar sinyal terminasi diteruskan dan listener dilepas saat keluar/error. Ini menghindari proses yatim pada systemd dan menjaga perilaku shutdown tetap konsisten lintas platform. Override lingkungan:
  • OPENCLAW_BASH_YIELD_MS: yield default (md)
  • OPENCLAW_BASH_MAX_OUTPUT_CHARS: batas output dalam memori (karakter)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: batas stdout/stderr tertunda per stream (karakter)
  • OPENCLAW_BASH_JOB_TTL_MS: TTL untuk sesi yang selesai (md, dibatasi 1m–3j)
  • OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS: ambang output idle sebelum sesi latar belakang yang dapat ditulis ditandai kemungkinan menunggu input (default 15000 md)
Konfigurasi (disarankan):
  • tools.exec.backgroundMs (default 10000)
  • tools.exec.timeoutSec (default 1800)
  • tools.exec.cleanupMs (default 1800000)
  • tools.exec.notifyOnExit (default true): antrekan event sistem + minta Heartbeat saat exec latar belakang keluar.
  • tools.exec.notifyOnExitEmptySuccess (default false): ketika true, juga antrekan event penyelesaian untuk proses latar belakang yang berhasil tetapi tidak menghasilkan output.

​
alat process

Tindakan:
  • list: sesi berjalan + selesai
  • poll: kuras output baru untuk sebuah sesi (juga melaporkan status keluar)
  • log: baca output agregat dan tampilkan petunjuk pemulihan input (mendukung offset + limit)
  • write: kirim stdin (data, eof opsional)
  • send-keys: kirim token tombol eksplisit atau byte ke sesi berbasis PTY
  • submit: kirim Enter / carriage return ke sesi berbasis PTY
  • paste: kirim teks literal, opsional dibungkus dalam mode paste bertanda kurung
  • kill: hentikan sesi latar belakang
  • clear: hapus sesi selesai dari memori
  • remove: hentikan jika sedang berjalan, jika tidak bersihkan jika selesai
Catatan:
  • Hanya sesi latar belakang yang dicantumkan/disimpan di memori.
  • Sesi hilang saat proses dimulai ulang (tidak ada persistensi disk).
  • Log sesi hanya disimpan ke riwayat chat jika Anda menjalankan process poll/log dan hasil alat direkam.
  • process tercakup per agent; alat ini hanya melihat sesi yang dimulai oleh agent tersebut.
  • Gunakan poll / log untuk status, log, konfirmasi keberhasilan senyap, atau konfirmasi penyelesaian saat pemicu bangun penyelesaian otomatis tidak tersedia.
  • Gunakan log sebelum memulihkan CLI interaktif agar transkrip saat ini, status stdin, dan petunjuk tunggu-input terlihat bersama.
  • Gunakan write / send-keys / submit / paste / kill saat Anda memerlukan input atau intervensi.
  • process list menyertakan name turunan (kata kerja perintah + target) untuk pemindaian cepat.
  • process list, poll, dan log melaporkan waitingForInput hanya saat sesi masih memiliki stdin yang dapat ditulis dan telah idle lebih lama dari ambang tunggu-input.
  • process log menggunakan offset/limit berbasis baris.
  • Ketika offset dan limit sama-sama dihilangkan, alat mengembalikan 200 baris terakhir dan menyertakan petunjuk paging.
  • Ketika offset diberikan dan limit dihilangkan, alat mengembalikan dari offset hingga akhir (tidak dibatasi 200).
  • Polling digunakan untuk status sesuai permintaan, bukan penjadwalan loop tunggu. Jika pekerjaan harus terjadi nanti, gunakan cron sebagai gantinya.

​
Contoh

Jalankan tugas panjang dan poll nanti: 
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }
Periksa sesi interaktif sebelum mengirim input: 
{ "tool": "process", "action": "log", "sessionId": "<id>" }
Mulai langsung di latar belakang: 
{ "tool": "exec", "command": "npm run build", "background": true }
Kirim stdin: 
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
Kirim tombol PTY: 
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
Kirim baris saat ini: 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Tempel teks literal: 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
Terkait