Exec tool

Chạy các lệnh shell trong workspace. Hỗ trợ chạy foreground + background thông qua process. Nếu process bị vô hiệu hóa, exec sẽ chạy đồng bộ và bỏ qua yieldMs/background. Các session background được phân tách theo agent; process chỉ thấy các session từ cùng một agent.

Tham số

command (bắt buộc)
workdir (mặc định là thư mục hiện tại)
env (ghi đè các biến môi trường theo key/value)
yieldMs (mặc định 10000): tự động chuyển sang background sau khoảng thời gian này
background (bool): chuyển sang background ngay lập tức
timeout (giây, mặc định 1800): kill process khi hết thời gian
pty (bool): chạy trong pseudo-terminal khi có sẵn (dành cho các CLI chỉ chạy trên TTY, coding agents, terminal UIs)
host (sandbox | gateway | node): nơi thực thi lệnh
security (deny | allowlist | full): chế độ bảo mật cho gateway/node
ask (off | on-miss | always): yêu cầu phê duyệt cho gateway/node
node (string): node id/name khi dùng host=node
elevated (bool): yêu cầu chế độ elevated (gateway host); security=full chỉ được bắt buộc khi elevated resolve thành full

Lưu ý:

host mặc định là sandbox.
elevated bị bỏ qua khi sandboxing tắt (exec đã chạy trực tiếp trên host).
Phê duyệt cho gateway/node được quản lý bởi ~/.openclaw/exec-approvals.json.
node yêu cầu một node đã được paired (companion app hoặc headless node host).
Nếu có nhiều node, các bạn cần set exec.node hoặc tools.exec.node để chọn node cụ thể.
Trên các host không phải Windows, exec dùng SHELL khi được set; nếu SHELL là fish, nó sẽ ưu tiên bash (hoặc sh) từ PATH để tránh các script không tương thích với fish, sau đó mới fallback về SHELL nếu không tìm thấy.
Host execution (gateway/node) từ chối env.PATH và các loader overrides (LD_*/DYLD_*) để ngăn chặn binary hijacking hoặc injected code.
Quan trọng: sandboxing mặc định tắt. Nếu sandboxing tắt, host=sandbox sẽ chạy trực tiếp trên gateway host (không có container) và không yêu cầu phê duyệt. Để yêu cầu phê duyệt, chạy với host=gateway và cấu hình exec approvals (hoặc bật sandboxing).

Config

tools.exec.notifyOnExit (mặc định: true): khi true, các session exec chạy background sẽ tạo system event và yêu cầu heartbeat khi kết thúc.
tools.exec.approvalRunningNoticeMs (mặc định: 10000): hiển thị một thông báo “running” duy nhất khi exec cần phê duyệt chạy lâu hơn thời gian này (0 để tắt).
tools.exec.host (mặc định: sandbox)
tools.exec.security (mặc định: deny cho sandbox, allowlist cho gateway + node khi không set)
tools.exec.ask (mặc định: on-miss)
tools.exec.node (mặc định: không set)
tools.exec.pathPrepend: danh sách các thư mục để thêm vào đầu PATH khi chạy exec.
tools.exec.safeBins: các binary an toàn chỉ dùng stdin, có thể chạy mà không cần thêm vào allowlist.

Ví dụ:

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

Xử lý PATH

host=gateway: merge PATH từ login-shell của các bạn vào môi trường exec. Các override env.PATH bị từ chối khi chạy trên host. Daemon vẫn chạy với PATH tối thiểu:
- macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
- Linux: /usr/local/bin, /usr/bin, /bin
host=sandbox: chạy sh -lc (login shell) bên trong container, nên /etc/profile có thể reset PATH. OpenClaw thêm env.PATH vào đầu sau khi source profile thông qua một biến môi trường nội bộ (không có shell interpolation); tools.exec.pathPrepend cũng áp dụng ở đây.
host=node: chỉ các env override không bị block mới được gửi đến node. Các override env.PATH bị từ chối khi chạy trên host. Headless node hosts chấp nhận PATH chỉ khi nó thêm vào đầu PATH của node host (không thay thế). macOS nodes bỏ qua hoàn toàn các override PATH.

Binding node theo agent (dùng index trong danh sách agent ở config):

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

Control UI: tab Nodes có panel nhỏ “Exec node binding” cho các cài đặt tương tự.

Session overrides (`/exec`)

Dùng /exec để set các giá trị mặc định theo session cho host, security, ask, và node. Gửi /exec không có tham số để xem các giá trị hiện tại.

Ví dụ:

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

Authorization model

/exec chỉ được chấp nhận từ authorized senders (channel allowlists/pairing cộng với commands.useAccessGroups). Nó chỉ cập nhật session state và không ghi vào config. Để vô hiệu hóa hoàn toàn exec, từ chối nó qua tool policy (tools.deny: ["exec"] hoặc theo agent). Host approvals vẫn áp dụng trừ khi các bạn set rõ ràng security=full và ask=off.

Exec approvals (companion app / node host)

Các agent được sandbox có thể yêu cầu phê duyệt từng request trước khi exec chạy trên gateway hoặc node host. Xem Exec approvals để biết về policy, allowlist và UI flow.

Khi cần phê duyệt, exec tool sẽ trả về ngay lập tức với status: "approval-pending" và một approval id. Sau khi được phê duyệt (hoặc bị từ chối / timeout), Gateway sẽ phát ra system events (Exec finished / Exec denied). Nếu lệnh vẫn đang chạy sau tools.exec.approvalRunningNoticeMs, một thông báo Exec running duy nhất sẽ được phát ra.

Allowlist + safe bins

Allowlist enforcement chỉ khớp với resolved binary paths (không khớp basename). Khi security=allowlist, các lệnh shell chỉ được tự động cho phép nếu mọi segment trong pipeline đều nằm trong allowlist hoặc là safe bin. Chaining (;, &&, ||) và redirections bị từ chối trong chế độ allowlist.

Ví dụ

Foreground:

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

Background + poll:

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

Send keys (kiểu tmux):

{"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"]}

Submit (chỉ gửi CR):

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

Paste (mặc định có bracketed):

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

apply_patch (thử nghiệm)

apply_patch là một subtool của exec dùng để chỉnh sửa nhiều file có cấu trúc. Bật nó một cách rõ ràng:

{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
    },
  },
}