​

Công cụ Exec

​

Tham số

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

• host mặc định là sandbox.
• elevated bị bỏ qua khi sandboxing tắt (exec đã chạy trên host).
• Phê duyệt gateway/node được kiểm soát bởi ~/.openclaw/exec-approvals.json.
• node yêu cầu một node ghép đôi (ứng dụng đồng hành hoặc host node không có giao diện).
• Nếu có nhiều node, đặt exec.node hoặc tools.exec.node để chọn một.
• Trên các host không phải Windows, exec sử dụng SHELL khi được đặt; nếu SHELL là fish, nó ưu tiên bash (hoặc sh) từ PATH để tránh các script không tương thích với fish, sau đó quay lại SHELL nếu không có.
• Trên các host Windows, exec ưu tiên phát hiện PowerShell 7 (pwsh) (Program Files, ProgramW6432, sau đó PATH), sau đó quay lại Windows PowerShell 5.1.
• Thực thi trên host (gateway/node) từ chối env.PATH và ghi đè loader (LD_*/DYLD_*) để ngăn chặn việc chiếm quyền điều khiển binary hoặc mã được chèn vào.
• OpenClaw đặt OPENCLAW_SHELL=exec trong môi trường lệnh được khởi chạy (bao gồm cả PTY và thực thi sandbox) để các quy tắc shell/profile có thể phát hiện ngữ cảnh công cụ exec.
• Quan trọng: sandboxing tắt theo mặc định. Nếu sandboxing tắt và host=sandbox được cấu hình/yêu cầu rõ ràng, exec sẽ thất bại thay vì chạy âm thầm trên host gateway. Bật sandboxing hoặc sử dụng host=gateway với phê duyệt.
• Kiểm tra trước script (cho các lỗi cú pháp shell Python/Node phổ biến) chỉ kiểm tra các tệp bên trong ranh giới workdir hiệu quả. Nếu một đường dẫn script nằm ngoài workdir, kiểm tra trước sẽ bị bỏ qua cho tệp đó.

​

Cấu hình

• tools.exec.notifyOnExit (mặc định: true): khi true, các phiên exec chuyển sang background sẽ xếp hàng một sự kiện hệ thống và yêu cầu một nhịp tim khi thoát.
• tools.exec.approvalRunningNoticeMs (mặc định: 10000): phát ra một thông báo “đang chạy” khi một exec yêu cầu 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 được đặt)
• tools.exec.ask (mặc định: on-miss)
• tools.exec.node (mặc định: không đặt)
• tools.exec.pathPrepend: danh sách các thư mục để thêm vào đầu PATH cho các lần chạy exec (chỉ dành cho gateway + sandbox).
• tools.exec.safeBins: các binary an toàn chỉ dành cho stdin có thể chạy mà không cần các mục allowlist rõ ràng. Để biết chi tiết hành vi, xem Safe bins.
• tools.exec.safeBinTrustedDirs: các thư mục rõ ràng bổ sung được tin cậy cho các kiểm tra đường dẫn safeBins. Các mục PATH không bao giờ được tự động tin cậy. Mặc định tích hợp là /bin và /usr/bin.
• tools.exec.safeBinProfiles: chính sách argv tùy chọn cho từng safe bin (minPositional, maxPositional, allowedValueFlags, deniedFlags).

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

​

Xử lý PATH

• host=gateway: hợp nhất PATH của shell đăng nhập vào môi trường exec. Các ghi đè env.PATH bị từ chối cho thực thi trên host. Daemon tự chạy với một 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 (shell đăng nhập) bên trong container, vì vậy /etc/profile có thể đặt lại PATH. OpenClaw thêm env.PATH sau khi nguồn profile thông qua một biến môi trường nội bộ (không có nội suy shell); tools.exec.pathPrepend cũng áp dụng ở đây.
• host=node: chỉ các ghi đè env không bị chặn bạn gửi mới được gửi đến node. Các ghi đè env.PATH bị từ chối cho thực thi trên host và bị node hosts bỏ qua. Nếu bạn cần thêm các mục PATH trên một node, cấu hình môi trường dịch vụ host node (systemd/launchd) hoặc cài đặt công cụ ở các vị trí tiêu chuẩn.

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

​

Ghi đè phiên (/exec)

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

​

Mô hình ủy quyền

​

Phê duyệt Exec (ứng dụng đồng hành / host node)

​

Allowlist + safe bins

• tools.exec.safeBins: bộ lọc luồng chỉ dành cho stdin nhỏ.
• tools.exec.safeBinTrustedDirs: các thư mục tin cậy bổ sung rõ ràng cho các đường dẫn thực thi safe-bin.
• tools.exec.safeBinProfiles: chính sách argv rõ ràng cho các safe bin tùy chỉnh.
• allowlist: tin tưởng rõ ràng cho các đường dẫn thực thi.

​

Ví dụ

{ "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 (thử nghiệm)

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

• Chỉ có sẵn cho các mô hình OpenAI/OpenAI Codex.
• Chính sách công cụ vẫn áp dụng; allow: ["exec"] ngầm cho phép apply_patch.
• Cấu hình nằm dưới tools.exec.applyPatch.
• tools.exec.applyPatch.workspaceOnly mặc định là true (chỉ trong workspace). Đặt nó thành false chỉ khi bạn muốn apply_patch ghi/xóa ngoài thư mục workspace.