Exec approvals

Exec approvals là cơ chế bảo vệ của companion app / node host để cho phép Agent trong Sandbox chạy lệnh trên host thật (gateway hoặc node). Các bạn có thể hiểu nó như một khóa an toàn: lệnh chỉ được phép chạy khi policy + allowlist + (tùy chọn) phê duyệt của người dùng đều đồng ý.

Exec approvals hoạt động bổ sung cho tool policy và elevated gating (trừ khi elevated được đặt thành full, sẽ bỏ qua approvals).

Policy hiệu lực là giá trị nghiêm ngặt hơn giữa tools.exec.* và approvals defaults; nếu một trường approvals bị bỏ qua, giá trị tools.exec sẽ được dùng.

Nếu companion app UI không khả dụng, mọi yêu cầu cần prompt sẽ được xử lý bởi ask fallback (mặc định: deny).

Phạm vi áp dụng

Exec approvals được thực thi cục bộ trên execution host:

  • gateway host → tiến trình openclaw trên máy gateway
  • node host → node runner (macOS companion app hoặc headless node host)

Phân chia trên macOS:

  • node host service chuyển tiếp system.run đến macOS app qua local IPC.
  • macOS app thực thi approvals + chạy lệnh trong UI context.

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

Approvals được lưu trong file JSON cục bộ trên execution host:

~/.openclaw/exec-approvals.json

Ví dụ schema:

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

Các tùy chọn policy

Security (exec.security)

  • deny: chặn tất cả yêu cầu exec trên host.
  • allowlist: chỉ cho phép các lệnh trong allowlist.
  • full: cho phép mọi thứ (tương đương elevated).

Ask (exec.ask)

  • off: không bao giờ hỏi.
  • on-miss: chỉ hỏi khi allowlist không khớp.
  • always: hỏi với mọi lệnh.

Ask fallback (askFallback)

Nếu cần prompt nhưng không có UI khả dụng, fallback sẽ quyết định:

  • deny: chặn.
  • allowlist: chỉ cho phép nếu allowlist khớp.
  • full: cho phép.

Allowlist (theo từng agent)

Allowlists được cấu hình theo từng agent. Nếu có nhiều agent, các bạn chuyển đổi agent đang chỉnh sửa trong macOS app. Patterns là glob matches không phân biệt chữ hoa/thường.

Patterns nên resolve thành binary paths (các entry chỉ có basename sẽ bị bỏ qua).

Các entry agents.default cũ sẽ được migrate sang agents.main khi load.

Ví dụ:

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

Mỗi allowlist entry theo dõi:

  • id UUID ổn định dùng cho UI identity (tùy chọn)
  • last used timestamp
  • last used command
  • last resolved path

Auto-allow skill CLIs

Khi Auto-allow skill CLIs được bật, các executable được tham chiếu bởi các skill đã biết sẽ được coi như đã có trong allowlist trên nodes (macOS node hoặc headless node host). Tính năng này dùng skills.bins qua Gateway RPC để lấy danh sách skill bin. Tắt tính năng này nếu các bạn muốn allowlist thủ công nghiêm ngặt.

Safe bins (stdin-only)

tools.exec.safeBins định nghĩa một danh sách nhỏ các binary chỉ dùng stdin (ví dụ jq) có thể chạy trong allowlist mode mà không cần allowlist entries rõ ràng. Safe bins từ chối positional file args và path-like tokens, nên chúng chỉ có thể xử lý incoming stream.

Shell chaining và redirections không được tự động cho phép trong allowlist mode.

Shell chaining (&&, ||, ;) được cho phép khi mọi top-level segment thỏa mãn allowlist (bao gồm safe bins hoặc skill auto-allow). Redirections vẫn không được hỗ trợ trong allowlist mode.

Safe bins mặc định: jq, grep, cut, sort, uniq, head, tail, tr, wc.

Chỉnh sửa trong Control UI

Dùng card Control UI → Nodes → Exec approvals để chỉnh sửa defaults, per-agent overrides, và allowlists. Chọn một scope (Defaults hoặc một agent), điều chỉnh policy, thêm/xóa allowlist patterns, rồi Save. UI hiển thị metadata last used cho mỗi pattern để các bạn có thể giữ danh sách gọn gàng.

Target selector chọn Gateway (local approvals) hoặc một Node. Nodes phải advertise system.execApprovals.get/set (macOS app hoặc headless node host).

Nếu một node chưa advertise exec approvals, các bạn chỉnh sửa trực tiếp file ~/.openclaw/exec-approvals.json cục bộ của nó.

CLI: openclaw approvals hỗ trợ chỉnh sửa gateway hoặc node (xem Approvals CLI).

Luồng phê duyệt

Khi cần prompt, gateway broadcast exec.approval.requested đến operator clients. Control UI và macOS app resolve nó qua exec.approval.resolve, sau đó gateway chuyển tiếp yêu cầu đã được phê duyệt đến node host.

Khi approvals được yêu cầu, exec tool trả về ngay lập tức với một approval id. Dùng id đó để tương quan với các system events sau này (Exec finished / Exec denied). Nếu không có quyết định nào đến trước timeout, yêu cầu sẽ được coi là approval timeout và hiển thị như một lý do từ chối.

Hộp thoại xác nhận bao gồm:

  • command + args
  • cwd
  • agent id
  • resolved executable path
  • host + policy metadata

Các hành động:

  • Allow once → chạy ngay
  • Always allow → thêm vào allowlist + chạy
  • Deny → chặn

Chuyển tiếp approval đến chat channels

Các bạn có thể chuyển tiếp exec approval prompts đến bất kỳ chat channel nào (bao gồm plugin channels) và phê duyệt chúng bằng /approve. Tính năng này dùng normal outbound delivery pipeline.

Config:

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // substring or regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

Trả lời trong chat:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

Luồng macOS IPC

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

Lưu ý bảo mật:

  • Unix socket mode 0600, token được lưu trong exec-approvals.json.
  • Same-UID peer check.
  • Challenge/response (nonce + HMAC token + request hash) + short TTL.

System events

Vòng đời exec được hiển thị dưới dạng system messages:

  • Exec running (chỉ khi lệnh vượt quá running notice threshold)
  • Exec finished
  • Exec denied

Các message này được đăng lên session của agent sau khi node báo cáo event.

Gateway-host exec approvals phát ra các lifecycle events tương tự khi lệnh kết thúc (và tùy chọn khi chạy lâu hơn threshold).

Approval-gated execs tái sử dụng approval id làm runId trong các message này để dễ tương quan.

Ý nghĩa

  • full rất mạnh; ưu tiên dùng allowlists khi có thể.
  • ask giúp các bạn nắm được tình hình trong khi vẫn cho phép phê duyệt nhanh.
  • Per-agent allowlists ngăn approvals của một agent rò rỉ sang agent khác.
  • Approvals chỉ áp dụng cho host exec requests từ authorized senders. Unauthorized senders không thể issue /exec.
  • /exec security=full là tiện ích session-level cho authorized operators và bỏ qua approvals theo thiết kế. Để chặn cứng host exec, đặt approvals security thành deny hoặc deny exec tool qua tool policy.

Liên quan: