Phê duyệt thực thi

Phê duyệt exec là lan can bảo vệ của ứng dụng đồng hành / host node để cho phép một tác nhân trong sandbox chạy lệnh trên một host thật (gateway hoặc node). Một khóa liên động an toàn: lệnh chỉ được phép khi policy + allowlist + (phê duyệt người dùng tùy chọn) đều đồng ý. Phê duyệt exec xếp chồng lên trên policy công cụ và cổng elevated (trừ khi elevated được đặt thành full, khi đó bỏ qua phê duyệt).

Kiểm tra policy hiệu lực

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ý khi chạy thay vì giả vờ rằng tệp phê duyệt cục bộ là nguồn sự thật.

Nếu giao diện ứng dụng đồng hành không khả dụng, mọi yêu cầu thường sẽ nhắc đều được giải quyết bằng ask fallback (mặc định: deny).

Nơi áp dụng

Phê duyệt exec được thực thi cục bộ trên host thực thi:

• Host Gateway → tiến trình openclaw trên máy gateway.
• Host node → trình chạy node (ứng dụng đồng hành macOS hoặc host node headless).

Mô hình tin cậy

• Các caller đã xác thực qua Gateway là operator đáng tin cậy cho Gateway đó.
• Các node đã ghép đôi mở rộng năng lực operator đáng tin cậy đó lên host node.
• Phê duyệt exec 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 hay policy filesystem chỉ đọc.
• Sau khi được phê duyệt, một lệnh có thể thay đổi tệp theo quyền host hoặc sandbox filesystem đã chọn.
• Các lần chạy trên host node đã được phê duyệt ràng buộc ngữ cảnh thực thi chuẩn: cwd chuẩn, argv chính xác, ràng buộc env khi có, và đường dẫn executable được ghim khi áp dụng.
• Với shell script và các lệnh gọi tệp trực tiếp qua interpreter/runtime, OpenClaw cũng cố gắng ràng buộc một toán hạng tệp cục bộ cụ thể. Nếu tệp đã ràng buộc đó thay đổi sau khi phê duyệt nhưng trước khi thực thi, lần chạy bị từ chối thay vì thực thi nội dung đã lệch.
• Ràng buộc tệp cố ý là nỗ lực tốt nhất, không phải mô hình ngữ nghĩa hoàn chỉnh cho mọi đường dẫn loader interpreter/runtime. Nếu chế độ phê duyệt không thể xác định chính xác một tệp cục bộ cụ thể để ràng buộc, nó từ chối tạo một lần chạy được phê duyệt hậu thuẫn thay vì giả vờ có độ bao phủ đầy đủ.

Tách biệt trên macOS

• Dịch vụ host 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.

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

Phê duyệt nằm trong một tệp JSON cục bộ trên host thực thi:

~/.openclaw/exec-approvals.json

Lược đồ ví dụ:

{  "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",          "commandText": "rg -n TODO",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

Núm policy

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Ví dụ mà chế độ nghiêm ngặt bắt được:

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

Trong chế độ nghiêm ngặt, các lệnh này vẫn cần phê duyệt rõ ràng, và allow-always không tự động lưu bền các mục allowlist mới cho chúng.

tools.exec.commandHighlighting

Cài đặt này không thay đổi security, ask, so khớp allowlist, hành vi strict inline-eval, chuyển tiếp phê duyệt, hay thực thi lệnh. Có thể đặt toàn cục dưới tools.exec.commandHighlighting hoặc theo từng tác nhân dưới agents.list[].tools.exec.commandHighlighting.

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

Nếu muốn host exec chạy mà không có lời nhắc phê duyệt, bạn phải mở cả hai lớp policy - policy exec được yêu cầu trong cấu hình OpenClaw (tools.exec.*) và policy phê duyệt cục bộ của host trong ~/.openclaw/exec-approvals.json.

YOLO là hành vi mặc định của host trừ khi bạn siết chặt rõ ràng:

Các provider dựa trên CLI có cung cấp chế độ quyền không tương tác riêng có thể tuân theo policy này. Claude CLI thêm --permission-mode bypassPermissions khi policy exec được yêu cầu của OpenClaw là YOLO. Ghi đè hành vi backend đó bằng các đối số Claude rõ ràng dưới agents.defaults.cliBackends.claude-cli.args / resumeArgs - ví dụ --permission-mode default, acceptEdits, hoặc bypassPermissions.

Nếu muốn thiết lập bảo thủ hơn, hãy siết một trong hai lớp trở lại allowlist / on-miss hoặc deny.

Thiết lập "không bao giờ nhắc" bền vững cho gateway-host

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

Lối tắt cục bộ đó cập nhật cả hai:

• tools.exec.host/security/ask cục bộ.
• Mặc định ~/.openclaw/exec-approvals.json cục bộ.

Nó cố ý chỉ áp dụng cục bộ. Để thay đổi phê duyệt gateway-host hoặc node-host từ xa, dùng openclaw approvals set --gateway hoặc openclaw approvals set --node <id|name|ip>.

Host node

Với host node, áp dụng cùng tệp phê duyệt trên node đó thay vào đó:

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

Lối tắt chỉ cho phiên

• /exec security=full ask=off chỉ thay đổi phiên hiện tại.
• /elevated full là lối tắt phá kính khẩn cấp cũng bỏ qua phê duyệt exec cho phiên đó.

Nếu tệp phê duyệt host vẫn nghiêm ngặt hơn cấu hình, policy host nghiêm ngặt hơn vẫn thắng.

Allowlist (theo tác nhân)

Allowlist là theo tác nhân. Nếu có nhiều tác nhân, hãy chuyển tác nhân bạn đang chỉnh sửa trong ứng dụng macOS. Pattern là so khớp glob.

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

Các mục agents.default cũ được di trú sang agents.main khi tải. Các chuỗi shell như echo ok && pwd vẫn cần mọi đoạn cấp cao nhất thỏa mãn quy tắc allowlist.

Ví dụ:

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

Giới hạn đối số bằng argPattern

Thêm argPattern khi một mục allowlist cần khớp một binary và một hình dạng đối số cụ thể. OpenClaw đánh giá biểu thức chính quy trên các đối số lệnh đã phân tích, loại trừ token executable (argv[0]). Với các mục viết tay, đối số được nối bằng một dấu cách đơn, vì vậy hãy neo pattern 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 là một allowlist miss. Nếu một mục chỉ theo đường dẫn cho cùng binary cũng có mặt, các đối số không khớp vẫn có thể fallback về mục chỉ theo đường dẫn đó. Bỏ qua mục chỉ theo đường dẫn khi mục tiêu là giới hạn binary ở các đối số đã khai báo.

Các mục được lưu bởi luồng phê duyệt có thể dùng định dạng dấu phân tách nội bộ để khớp argv chính xác. Ưu tiên dùng UI 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 đoạn lệnh, các mục có argPattern sẽ không khớp.

Mỗi mục allowlist hỗ trợ:

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

Khi bật Tự động cho phép CLI của skill, các tệp thực thi được tham chiếu bởi những skill đã biết được xem là nằm trong allowlist 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 Gateway RPC để lấy danh sách bin của skill. Tắt tùy chọn này nếu bạn muốn allowlist thủ công nghiêm ngặt.

Bin an toàn và chuyển tiếp phê duyệt

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

Chỉnh sửa UI điều khiển

Dùng thẻ UI điều khiển → Node → Phê duyệt exec để chỉnh sửa mặc định, ghi đè theo agent và allowlist. Chọn một phạm vi (Mặc định hoặc một agent), điều chỉnh chính sách, thêm/xóa mẫu allowlist, rồi Lưu. UI hiển thị siêu dữ liệu lần dùng gần nhất theo từng mẫu để bạn có thể giữ danh sách gọn gàng.

Bộ chọn mục tiêu chọn Gateway (phê duyệt cục bộ) hoặc một Node. 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 ~/.openclaw/exec-approvals.json cục bộ của Node đó.

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 tới các máy khách vận hành. UI điều khiển và ứng dụng macOS giải quyết yêu cầu qua exec.approval.resolve, sau đó Gateway chuyển tiếp yêu cầu đã được phê duyệt tới máy chủ Node.

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 command/cwd/session có thẩm quyền khi chuyển tiếp các yêu cầu system.run đã được phê duyệt.

Điều đó quan trọng đối với độ trễ phê duyệt bất đồng bộ:

• Đườ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 kế hoạch đó và siêu dữ liệu ràng buộc 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 vào 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 vì phê duyệt không khớp.

Sự kiện hệ thống

Vòng đời exec được hiển thị dưới dạng thông báo hệ thống:

• Exec running (chỉ khi lệnh vượt quá ngưỡng thông báo đang chạy).
• Exec finished.
• Exec denied.

Các thông báo này được đăng vào phiên của agent sau khi Node báo cáo sự kiện. Phê duyệt exec do Gateway lưu trữ phát cùng các sự kiện vòng đời khi lệnh hoàn tất (và tùy chọn khi chạy lâu hơn ngưỡng). Các exec có cổng phê duyệt tái sử dụng id phê duyệt làm runId trong những thông báo này để dễ đối chiếu.

Hành vi khi phê duyệt bị từ chối

Khi một phê duyệt exec bất đồng bộ bị từ chối, OpenClaw ngăn agent tái sử dụng đầu ra từ bất kỳ lần chạy trước nào của cùng lệnh trong phiên. Lý do từ chối được truyền kèm hướng dẫn tường minh rằng không có đầu ra lệnh nào khả dụng, điều này ngăn agent tuyên bố có đầu ra mới hoặc lặp lại lệnh bị từ chối bằng kết quả cũ từ một lần chạy thành công trước đó.

Hàm ý

• full rất mạnh; ưu tiên dùng allowlist khi có thể.
• ask giữ bạn trong vòng kiểm soát trong khi vẫn cho phép phê duyệt nhanh.
• Allowlist theo agent ngăn phê duyệt của một agent rò rỉ sang agent khác.
• Phê duyệt chỉ áp dụng cho 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ể phát hành /exec.
• /exec security=full là tiện ích cấp phiên cho các vận hành viên được ủy quyền và bỏ qua phê duyệt theo thiết kế. Để 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 qua chính sách công cụ.

Liên quan