Phê duyệt thực thi

Phê duyệt thực thi là cơ chế bảo vệ của ứng dụng đồng hành / máy chủ Node để cho phép một tác tử trong sandbox chạy lệnh trên máy chủ thực (gateway hoặc node). Lệnh chỉ chạy khi chính sách + danh sách cho phép + phê duyệt (tùy chọn) của người dùng đều đồng thuận. Phê duyệt được xếp chồng lên trên chính sách công cụ và cổng kiểm soát đặc quyền nâng cao (chế độ đặc quyền nâng cao full bỏ qua chúng).

Để xem tổng quan theo chế độ về deny, allowlist, ask, auto, full, ánh xạ Codex Guardian và quyền của bộ khung ACPX, hãy xem Các chế độ quyền.

Phạm vi áp dụng

Phê duyệt thực thi được thực thi cục bộ trên máy chủ thực thi:

• Máy chủ Gateway -> tiến trình openclaw trên máy Gateway.
• Máy chủ Node -> trình chạy Node (ứng dụng đồng hành macOS hoặc máy chủ Node không giao diện).

Mô hình tin cậy

• Các bên gọi đã xác thực với Gateway là những người vận hành đáng tin cậy đối với Gateway đó.
• Các Node đã ghép cặp mở rộng năng lực của người vận hành đáng tin cậy đó sang máy chủ Node.
• Phê duyệt làm giảm rủi ro thực thi ngoài ý muốn, nhưng không phải là ranh giới xác thực theo từng người dùng hoặc chính sách chỉ đọc hệ thống tệp.
• Sau khi được phê duyệt, một lệnh có thể thay đổi tệp theo quyền hệ thống tệp của máy chủ hoặc sandbox đã chọn.
• Các lần chạy được phê duyệt trên máy chủ Node liên kết ngữ cảnh thực thi chuẩn tắc: cwd, argv chính xác, liên kết env khi có và đường dẫn tệp thực thi được ghim khi áp dụng.
• Đối với tập lệnh shell và việc gọi trực tiếp tệp của trình thông dịch/môi trường chạy, OpenClaw cũng cố gắng liên kết một toán hạng tệp cục bộ cụ thể. Nếu tệp đó thay đổi sau khi phê duyệt nhưng trước khi thực thi, lần chạy sẽ bị từ chối thay vì thực thi nội dung đã sai lệch.
• Liên kết tệp là nỗ lực tối đa, không phải mô hình hoàn chỉnh cho mọi đường dẫn nạp của trình thông dịch/môi trường chạy. Nếu không thể xác định chính xác một tệp cục bộ cụ thể, OpenClaw sẽ từ chối tạo lần chạy dựa trên phê duyệt thay vì giả vờ có phạm vi bảo vệ đầy đủ.

Phân tách trên macOS

• Dịch vụ máy chủ Node chuyển tiếp system.run đến ứng dụng macOS qua IPC cục bộ.
• Ứng dụng macOS thực thi phê duyệt và chạy lệnh trong ngữ cảnh giao diện người dùng.

Kiểm tra chính sách có hiệu lực

Tài liệu tham khảo CLI đầy đủ (cờ, đầu ra JSON, thêm/xóa danh sách cho phép): CLI phê duyệt.

Khi một phạm vi cục bộ yêu cầu host=node, exec-policy show báo cáo phạm vi đó là do Node quản lý trong thời gian chạy thay vì coi tệp phê duyệt cục bộ là nguồn dữ liệu chuẩn.

Nếu giao diện người dùng của ứng dụng đồng hành không khả dụng, mọi yêu cầu vốn thường cần xác nhận sẽ được giải quyết bằng phương án dự phòng khi yêu cầu xác nhận (mặc định: deny).

Cài đặt và lưu trữ

Phê duyệt nằm trong một tệp JSON cục bộ trên máy chủ thực thi. Khi OPENCLAW_STATE_DIR được đặt, tệp sẽ nằm trong thư mục trạng thái đó; nếu không, tệp sử dụng thư mục trạng thái mặc định của OpenClaw:

$OPENCLAW_STATE_DIR/exec-approvals.json# nếu không~/.openclaw/exec-approvals.json

Socket phê duyệt mặc định dùng cùng thư mục gốc: $OPENCLAW_STATE_DIR/exec-approvals.sock, hoặc ~/.openclaw/exec-approvals.sock khi biến chưa được đặt.

Các thư mục trạng thái là những phạm vi tin cậy độc lập. Khi OPENCLAW_STATE_DIR trỏ đến nơi khác, OpenClaw không bao giờ nhập hoặc lưu trữ ~/.openclaw/exec-approvals.json; hãy cấu hình phê duyệt riêng cho thư mục trạng thái tùy chỉnh. Doctor cũng chỉ nhập plugin-binding-approvals.json cũ khi nó thuộc về thư mục trạng thái đang hoạt động.

Lược đồ mẫu:

{  "version": 1,  "socket": {    "path": "~/.openclaw/exec-approvals.sock",    "token": "base64url-token"  },  "defaults": {    "security": "deny",    "ask": "on-miss",    "askFallback": "deny",    "autoAllowSkills": false  },  "agents": {    "main": {      "security": "allowlist",      "ask": "on-miss",      "askFallback": "deny",      "autoAllowSkills": true,      "allowlist": [        {          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",          "pattern": "~/Projects/**/bin/rg",          "source": "allow-always",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

Các nút điều chỉnh chính sách

tools.exec.mode

tools.exec.mode là bề mặt chính sách chuẩn hóa được ưu tiên cho thực thi trên máy chủ:

Các giá trị cũ tools.exec.security / tools.exec.ask vẫn được hỗ trợ và vẫn áp dụng ở mọi nơi mà mode chưa được đặt trong phạm vi đó.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Ví dụ mà chế độ nghiêm ngặt phát hiện: python -c, node -e/--eval/-p, ruby -e, perl -e/-E, php -r, lua -e, osascript -e (cùng với các dạng nội tuyến awk, sed, make, find -exec và xargs).

Trong chế độ nghiêm ngặt, các lệnh này cần người review hoặc phê duyệt rõ ràng. Với tools.exec.mode: "auto", người review có thể cấp phép cho một lần thực thi có rủi ro thấp khi lệnh có kế hoạch có thể thực thi được; nếu không, OpenClaw sẽ yêu cầu con người phê duyệt. Các phê duyệt lệnh Codex app-server chuyển đến phương án dự phòng của người review sẽ yêu cầu con người vì yêu cầu phê duyệt của chúng không cung cấp tệp thực thi đã phân giải có thể thực thi được. allow-always không lưu các mục danh sách cho phép mới cho lệnh đánh giá nội tuyến.

tools.exec.commandHighlighting

Đặt toàn cục trong tools.exec.commandHighlighting hoặc theo từng tác tử trong agents.list[].tools.exec.commandHighlighting.

Chế độ YOLO (không phê duyệt)

Để chạy thực thi trên máy chủ mà không có lời nhắc phê duyệt, hãy mở cả hai lớp chính sách: chính sách thực thi được yêu cầu trong cấu hình OpenClaw (tools.exec.*) và chính sách phê duyệt cục bộ của máy chủ trong tệp phê duyệt của máy chủ thực thi.

Giá trị askFallback bị bỏ qua sẽ mặc định là deny. Đặt rõ ràng askFallback của máy chủ thành full khi lời nhắc phê duyệt không có giao diện người dùng cần chuyển sang cho phép.

Các nhà cung cấp dựa trên CLI có chế độ quyền không tương tác riêng có thể tuân theo chính sách này. Claude CLI thêm --permission-mode bypassPermissions khi chính sách exec hiệu lực của OpenClaw là YOLO. Đối với các phiên Claude trực tiếp do OpenClaw quản lý, chính sách exec hiệu lực của OpenClaw có quyền quyết định cao hơn chế độ quyền gốc của Claude: YOLO chuẩn hóa các lần khởi chạy trực tiếp thành --permission-mode bypassPermissions, còn chính sách exec hiệu lực hạn chế chuẩn hóa các lần khởi chạy trực tiếp thành --permission-mode default, ngay cả khi các đối số backend Claude thô chỉ định một chế độ khác.

Nếu muốn thiết lập thận trọng hơn, hãy siết chặt chính sách exec của OpenClaw trở lại allowlist / on-miss hoặc deny.

Thiết lập "không bao giờ nhắc" cố định trên máy chủ gateway

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

openclaw approvals set --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Lối tắt cục bộ

openclaw exec-policy preset yolo

Cập nhật cả tools.exec.host/security/ask cục bộ và các giá trị mặc định của tệp phê duyệt cục bộ (bao gồm askFallback: "full"). Lệnh này được chủ ý giới hạn chỉ dùng cục bộ. Để thay đổi phê duyệt trên máy chủ gateway hoặc máy chủ node từ xa, hãy dùng openclaw approvals set --gateway hoặc openclaw approvals set --node <id|name|ip>.

Các preset tích hợp khác: cautious (host=gateway, security=allowlist, ask=on-miss, askFallback=deny) và deny-all (host=gateway, security=deny, ask=off, askFallback=deny). Áp dụng theo cùng cách: openclaw exec-policy preset cautious.

Để đặt từng trường riêng lẻ thay vì toàn bộ preset, hãy dùng openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> với bất kỳ tập con nào của các cờ đó.

Máy chủ Node

Thay vào đó, áp dụng cùng tệp phê duyệt trên node:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Lối tắt chỉ dành cho phiên

• /exec security=full ask=off chỉ thay đổi phiên hiện tại.
• /elevated full là lối tắt khẩn cấp bỏ qua phê duyệt exec chỉ khi cả chính sách được yêu cầu và tệp phê duyệt của máy chủ đều phân giải thành security: "full" và ask: "off". Tệp máy chủ nghiêm ngặt hơn, chẳng hạn như ask: "always", vẫn sẽ nhắc.

Nếu tệp phê duyệt của máy chủ vẫn nghiêm ngặt hơn cấu hình, chính sách máy chủ nghiêm ngặt hơn vẫn được ưu tiên.

Danh sách cho phép (theo từng tác nhân)

Danh sách cho phép áp dụng theo từng tác nhân. Nếu có nhiều tác nhân, hãy chuyển sang tác nhân mà bạn đang chỉnh sửa trong ứng dụng macOS. Các mẫu được đối sánh theo glob.

Mẫu có thể là glob đường dẫn nhị phân đã phân giải hoặc glob tên lệnh thuần. Tên thuần chỉ khớp với các lệnh được gọi thông qua PATH, vì vậy rg có thể khớp với /opt/homebrew/bin/rg khi lệnh là rg, nhưng không khớp với ./rg hoặc /tmp/rg. Hãy dùng glob đường dẫn để tin cậy một vị trí tệp nhị phân cụ thể.

Các mục agents.default cũ được di chuyển sang agents.main khi tải. Các chuỗi shell như echo ok && pwd vẫn yêu cầu mọi phân đoạn cấp cao nhất đáp ứng các quy tắc của danh sách cho phép.

Ví dụ:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Hạn chế đối số bằng argPattern

Thêm argPattern khi một mục trong danh sách cho phép cần khớp với một tệp nhị phân và một dạng đối số cụ thể. OpenClaw sử dụng ngữ nghĩa biểu thức chính quy ECMAScript (JavaScript) trên mọi máy chủ và đánh giá biểu thức dựa trên các đối số lệnh đã phân tích, không bao gồm token tệp thực thi (argv[0]). Đối với các mục được tạo thủ công, các đối số được nối bằng một dấu cách, vì vậy hãy neo mẫu khi cần khớp chính xác.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

Mục đó cho phép python3 safe.py; python3 other.py không khớp với danh sách cho phép. Nếu cũng có một mục chỉ theo đường dẫn cho cùng tệp nhị phân, các đối số không khớp vẫn có thể quay về mục chỉ theo đường dẫn đó. Hãy bỏ mục chỉ theo đường dẫn khi mục tiêu là giới hạn tệp nhị phân ở các đối số đã khai báo.

Các mục được lưu bởi luồng phê duyệt sử dụng định dạng dấu phân cách nội bộ để khớp argv chính xác. Nên dùng giao diện người dùng hoặc luồng phê duyệt để tạo lại các mục đó thay vì chỉnh sửa thủ công giá trị đã mã hóa. Nếu OpenClaw không thể phân tích argv cho một phân đoạn lệnh, các mục có argPattern sẽ không khớp.

Mỗi mục trong danh sách cho phép hỗ trợ:

Tự động cho phép CLI của Skills

Khi Tự động cho phép CLI của Skills (autoAllowSkills) được bật, các tệp thực thi được tham chiếu bởi các skill đã biết sẽ được coi là có trong danh sách cho phép trên các node (node macOS hoặc máy chủ node không giao diện). Cơ chế này dùng skills.bins qua RPC của Gateway để lấy danh sách tệp nhị phân của skill. Hãy tắt tùy chọn này nếu muốn sử dụng nghiêm ngặt danh sách cho phép thủ công.

Tệp nhị phân an toàn và chuyển tiếp phê duyệt

Để biết về các tệp nhị phân an toàn (đường dẫn nhanh chỉ dùng stdin), chi tiết liên kết trình thông dịch và cách chuyển tiếp lời nhắc phê duyệt đến Slack/Discord/Telegram (hoặc chạy chúng dưới dạng máy khách phê duyệt gốc), hãy xem Phê duyệt exec - nâng cao.

Chỉnh sửa trong giao diện điều khiển

Dùng thẻ Control UI -> Nodes -> Exec approvals để chỉnh sửa các giá trị mặc định, các ghi đè theo từng tác nhân và danh sách cho phép. Chọn một phạm vi (Defaults hoặc một tác nhân), điều chỉnh chính sách, thêm/xóa các mẫu trong danh sách cho phép, rồi chọn Save. Giao diện hiển thị siêu dữ liệu sử dụng gần nhất cho từng mẫu để bạn có thể giữ danh sách gọn gàng.

Bộ chọn đích chọn Gateway (phê duyệt cục bộ) hoặc một Node. Các node phải quảng bá system.execApprovals.get/set (ứng dụng macOS hoặc máy chủ node không giao diện). Nếu một node chưa quảng bá phê duyệt exec, hãy chỉnh sửa trực tiếp tệp phê duyệt cục bộ của node đó.

Một số máy chủ node, bao gồm ứng dụng đồng hành Windows, sở hữu định dạng chính sách phê duyệt khác. Giao diện điều khiển hiển thị các chính sách gốc của máy chủ này ở chế độ chỉ đọc. Hãy dùng ứng dụng đồng hành hoặc openclaw approvals set --node <id|name|ip> với dạng chính sách gốc để chỉnh sửa; xem CLI phê duyệt.

CLI: openclaw approvals hỗ trợ chỉnh sửa gateway hoặc node - xem CLI phê duyệt.

Luồng phê duyệt

Khi cần lời nhắc, gateway phát exec.approval.requested đến các máy khách của người vận hành. Giao diện điều khiển và ứng dụng macOS xử lý lời nhắc đó qua exec.approval.resolve, sau đó gateway chuyển tiếp yêu cầu đã phê duyệt đến máy chủ node.

Đối với host=node, yêu cầu phê duyệt bao gồm payload systemRunPlan chuẩn tắc. Gateway dùng kế hoạch đó làm ngữ cảnh lệnh/cwd/phiên có thẩm quyền khi chuyển tiếp các yêu cầu system.run đã phê duyệt:

• Đường dẫn exec của node chuẩn bị trước một kế hoạch chuẩn tắc duy nhất.
• Bản ghi phê duyệt lưu trữ kế hoạch đó và siêu dữ liệu liên kết của nó.
• Sau khi được phê duyệt, lệnh gọi system.run được chuyển tiếp cuối cùng sẽ tái sử dụng kế hoạch đã lưu thay vì tin tưởng các chỉnh sửa sau đó của bên gọi.
• Nếu bên gọi thay đổi command, rawCommand, cwd, agentId hoặc sessionKey sau khi yêu cầu phê duyệt được tạo, gateway sẽ từ chối lần chạy được chuyển tiếp do phê duyệt không khớp.

Sự kiện hệ thống và từ chối

Vòng đời exec đăng thông báo hệ thống Exec finished vào phiên của tác nhân sau khi node báo cáo hoàn tất. OpenClaw cũng có thể phát thông báo đang xử lý sau khi phê duyệt được cấp và tools.exec.approvalRunningNoticeMs trôi qua (mặc định 10000, 0 sẽ tắt tính năng này). Phê duyệt exec bị từ chối sẽ kết thúc lệnh trên máy chủ: lệnh không chạy.

• Đối với các phê duyệt bất đồng bộ của tác nhân chính có phiên khởi nguồn, OpenClaw đăng quyết định từ chối trở lại phiên đó dưới dạng thông báo tiếp nối nội bộ để tác nhân có thể ngừng chờ lệnh bất đồng bộ và tránh phải sửa chữa do thiếu kết quả.
• Nếu không có phiên hoặc không thể tiếp tục phiên, OpenClaw vẫn có thể báo cáo ngắn gọn quyết định từ chối cho người vận hành hoặc qua tuyến trò chuyện trực tiếp.
• Các quyết định từ chối cho phiên tác nhân phụ và cron không được đăng trở lại phiên đó.

Phê duyệt exec trên máy chủ gateway phát cùng sự kiện vòng đời hoàn tất. Các lệnh exec có cổng phê duyệt tái sử dụng ID phê duyệt để liên kết yêu cầu đang chờ với thông báo hoàn tất/từ chối tương ứng (Exec finished (gateway id=...) / Exec denied (gateway id=...)).

Hệ quả

• full có quyền lực lớn; nên ưu tiên danh sách cho phép khi có thể.
• ask giúp bạn luôn nắm được tình hình trong khi vẫn cho phép phê duyệt nhanh.
• Danh sách cho phép theo từng tác nhân ngăn phê duyệt của một tác nhân bị rò rỉ sang tác nhân khác.
• Phê duyệt chỉ áp dụng cho các yêu cầu exec trên máy chủ từ người gửi được ủy quyền. Người gửi không được ủy quyền không thể gọi /exec.
• /exec security=full là tiện ích cấp phiên dành cho người vận hành được ủy quyền và chủ ý bỏ qua phê duyệt. Để chặn cứng exec trên máy chủ, hãy đặt bảo mật phê duyệt thành deny hoặc từ chối công cụ exec thông qua chính sách công cụ.

Liên quan