Alat eksekusi

​

Parameter

• host hanya menerima auto, sandbox, gateway, atau node. Ini bukan pemilih nama host; nilai yang menyerupai nama host ditolak sebelum perintah dijalankan.
• host=node per panggilan diizinkan dari auto; host=gateway per panggilan hanya diizinkan ketika tidak ada runtime sandbox yang aktif.
• Tanpa konfigurasi tambahan, host=auto tetap “langsung berfungsi”: tanpa sandbox, nilainya diresolusikan menjadi gateway; dengan sandbox aktif, nilainya tetap berada di dalam sandbox.
• elevated keluar dari sandbox ke jalur host yang dikonfigurasi: gateway secara default, atau node ketika tools.exec.host=node (atau nilai default sesi adalah host=node). Ini hanya tersedia ketika akses dengan hak istimewa yang ditingkatkan diaktifkan untuk sesi/penyedia saat ini.
• Persetujuan gateway/node dikendalikan oleh file persetujuan host.
• node memerlukan Node yang telah dipasangkan (aplikasi pendamping atau host Node tanpa antarmuka). Jika tersedia beberapa Node, tetapkan exec.node atau tools.exec.node untuk memilih salah satunya.
• exec host=node adalah satu-satunya jalur eksekusi shell untuk Node; pembungkus lama nodes.run telah dihapus.
• Pada host non-Windows, exec menggunakan SHELL jika ditetapkan; jika SHELL adalah fish, exec memprioritaskan bash (atau sh) dari PATH untuk menghindari konstruksi bash yang tidak kompatibel dengan fish, lalu kembali menggunakan SHELL jika keduanya tidak tersedia.
• Pada host Windows, exec memprioritaskan penemuan PowerShell 7 (pwsh) (Program Files, ProgramW6432, lalu PATH), kemudian kembali menggunakan Windows PowerShell 5.1.
• Pada host gateway non-Windows, perintah exec bash dan zsh menggunakan snapshot awal. OpenClaw menangkap alias/fungsi yang dapat dimuat dengan source serta sekumpulan kecil variabel lingkungan aman dari file awal shell ke dalam $OPENCLAW_STATE_DIR/cache/shell-snapshots/, lalu memuat snapshot tersebut dengan source sebelum setiap perintah exec. Variabel yang tampak seperti rahasia dikecualikan; exec sandbox dan Node tidak menggunakan snapshot ini. Tetapkan OPENCLAW_EXEC_SHELL_SNAPSHOT=0 dalam lingkungan proses Gateway untuk menonaktifkan jalur snapshot ini.
• Eksekusi host (gateway/node) menolak env.PATH dan penimpaan pemuat (LD_*/DYLD_*) untuk mencegah pembajakan biner atau injeksi kode.
• OpenClaw menetapkan OPENCLAW_SHELL=exec dalam lingkungan perintah yang dijalankan (termasuk eksekusi PTY dan sandbox) agar aturan shell/profil dapat mendeteksi konteks alat exec.
• Untuk proses yang berasal dari saluran, OpenClaw juga mengekspos payload JSON identitas pengirim/obrolan yang terbatas dalam OPENCLAW_CHANNEL_CONTEXT ketika saluran menyediakan id tersebut.
• exec tidak dapat menjalankan perintah shell openclaw channels login atau /approve: openclaw channels login adalah alur autentikasi saluran interaktif, dan /approve harus melalui penangan perintah persetujuan, bukan shell. Jalankan login saluran di terminal pada host gateway, atau gunakan alat agen login khusus saluran jika tersedia (misalnya whatsapp_login).
• Penting: sandbox nonaktif secara default. Jika sandbox nonaktif, host=auto implisit diresolusikan menjadi gateway. host=sandbox eksplisit tetap gagal secara tertutup alih-alih berjalan diam-diam pada host gateway. Aktifkan sandbox atau gunakan host=gateway dengan persetujuan.
• Pemeriksaan awal skrip (untuk kesalahan sintaks shell Python/Node yang umum) hanya memeriksa file di dalam batas efektif workdir. Jika jalur skrip diresolusikan ke luar workdir, pemeriksaan awal dilewati untuk file tersebut. Pemeriksaan awal juga dilewati sepenuhnya ketika host=gateway dan kebijakan efektifnya adalah security=full dengan ask=off.
• Untuk pekerjaan jangka panjang yang dimulai sekarang, mulai satu kali dan andalkan pemicu penyelesaian otomatis ketika diaktifkan dan perintah menghasilkan keluaran atau gagal. Gunakan process untuk log, status, masukan, atau intervensi; jangan meniru penjadwalan dengan perulangan tidur, perulangan batas waktu, atau polling berulang.
• Perintah latar belakang yang dimulai agen muncul dalam tampilan tugas latar belakang Web, iOS, dan Android hingga selesai. Buku besar tugas diselesaikan sebelum Heartbeat penyelesaian membangunkan agen kembali.
• Untuk pekerjaan yang harus dilakukan nanti atau sesuai jadwal, gunakan cron alih-alih pola tidur/penundaan exec.

​

Konfigurasi

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​

Mode

​

Evaluasi inline (strictInlineEval)

​

Penanganan PATH

• host=gateway: menggabungkan PATH shell login Anda ke dalam lingkungan eksekusi. Penggantian env.PATH ditolak untuk eksekusi host. Daemon itu sendiri tetap berjalan dengan PATH minimal:
  • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
  • Linux: /usr/local/bin, /usr/bin, /bin
  • Untuk mencegah konfigurasi shell pengguna (seperti ~/.zshenv atau /etc/zshenv) mengganti jalur prioritas selama proses mulai, entri tools.exec.pathPrepend ditambahkan secara aman di awal PATH akhir di dalam perintah shell tepat sebelum eksekusi.
• host=sandbox: menjalankan sh -lc (shell login) di dalam kontainer, sehingga /etc/profile dapat mengatur ulang PATH. OpenClaw menambahkan env.PATH di awal setelah pemuatan profil melalui variabel lingkungan internal (tanpa interpolasi shell); tools.exec.pathPrepend juga berlaku di sini.
• host=node: hanya penggantian lingkungan yang tidak diblokir dan Anda berikan yang dikirim ke node. Penggantian env.PATH ditolak untuk eksekusi host dan diabaikan oleh host node. Jika memerlukan entri PATH tambahan pada node, konfigurasikan lingkungan layanan host node (systemd/launchd) atau instal alat di lokasi standar.

openclaw config get agents.list
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

​

Penggantian sesi (/exec)

/exec host=auto security=allowlist ask=on-miss node=mac-1

​

Persetujuan eksekusi (aplikasi pendamping/host node)

​

Daftar izin + bin aman

• tools.exec.safeBins: filter aliran kecil yang hanya menggunakan stdin.
• tools.exec.safeBinTrustedDirs: direktori tepercaya tambahan yang eksplisit untuk jalur executable bin aman.
• tools.exec.safeBinProfiles: kebijakan argv eksplisit untuk bin aman kustom.
• allowlist: kepercayaan eksplisit untuk jalur executable.

​

Contoh

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

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

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

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

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

​

apply_patch

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.6-sol"] },
    },
  },
}

• Kebijakan alat tetap berlaku; allow: ["write"] secara implisit mengizinkan apply_patch.
• deny: ["write"] tidak menolak apply_patch; tolak apply_patch secara eksplisit atau gunakan deny: ["group:fs"] ketika penulisan patch juga harus diblokir.
• Konfigurasi berada di bawah tools.exec.applyPatch.
• tools.exec.applyPatch.enabled secara default bernilai true; atur nilainya menjadi false untuk menonaktifkan alat.
• tools.exec.applyPatch.workspaceOnly secara default bernilai true (dibatasi di dalam ruang kerja). Atur nilainya menjadi false hanya jika Anda memang bermaksud mengizinkan apply_patch menulis/menghapus di luar direktori ruang kerja.
• tools.exec.applyPatch.allowModels adalah daftar izin opsional untuk id model (mentah, seperti gpt-5.4, atau lengkap, seperti openai/gpt-5.4). Jika ditetapkan, hanya model yang cocok yang mendapatkan alat tersebut; jika tidak ditetapkan, semua model mendapatkannya.

​

Terkait

• Persetujuan Exec — gerbang persetujuan untuk perintah shell
• Sandboxing — menjalankan perintah dalam lingkungan sandbox
• Proses Latar Belakang — alat exec dan proses yang berjalan lama
• Keamanan — kebijakan alat dan akses dengan hak istimewa tinggi