# Hướng dẫn Cấu hình Managed Scope trong Hermes Agent
Tài liệu tóm tắt và hướng dẫn thực hành chi tiết về cơ chế **Managed Scope** của Hermes Agent, trích xuất từ tài liệu chính thức: [Hermes Agent - Managed Scope]( Managed Scope | Hermes Agent ).
-–
## 1. Tổng quan về Managed Scope (Overview)
### Managed Scope là gì?
**Managed Scope** là cơ chế cho phép **Quản trị viên hệ thống (Administrator / IT)** thiết lập và áp đặt một tập hợp cấu hình (`config.yaml`) và biến môi trường/secrets (`.env`) ở cấp độ hệ thống. Các giá trị này:
- **Bất biến đối với người dùng thông thường (User-immutable):** Người dùng thông thường (non-root) không thể ghi đè hoặc sửa đổi các khóa đã bị ghim.
- **Áp dụng cho toàn hệ thống:** Tất cả người dùng và tiến trình Hermes chạy trên máy sẽ tuân theo các chính sách này.
### Mục đích & Trường hợp sử dụng
- **Triển khai cấp tổ chức / Doanh nghiệp (Fleet/Org Deployments):** Đảm bảo tính đồng nhất trên hàng loạt máy trạm hoặc máy chủ.
- **Ép buộc chính sách bảo mật & endpoint:**
-
Ghim nhà cung cấp mô hình AI (`model.provider`).
-
Cố định địa chỉ API Gateway nội bộ (`OPENAI_API_BASE`).
-
Bắt buộc kích hoạt chế độ ẩn secrets (`security.redact_secrets: true`).
- **Phân tách quyền hạn thông minh (Leaf-level Merging):** Chỉ những khóa (keys) được Admin định nghĩa trong Managed Scope mới bị khóa cố định; các khóa còn lại người dùng vẫn toàn quyền cấu hình trong `~/.hermes/config.yaml` và `~/.hermes/.env`.
-–
## 2. Vị trí lưu trữ & Phân quyền tệp (File Structure & Permissions)
Mặc định trên hệ thống Linux/POSIX, Managed Scope được lưu tại thư mục `/etc/hermes/`:
```text
/etc/hermes/
├── config.yaml # Tầng cấu hình quản trị (Ưu tiên cao hơn ~/.hermes/config.yaml)
└── .env # Tầng biến môi trường quản trị (Ưu tiên cao hơn ~/.hermes/.env & Shell env)
```
### Cơ chế thực thi (Enforcement Mechanism)
Cơ chế bảo vệ dựa vào **phân quyền hệ thống tệp POSIX**:
- **Owner:** Thuộc sở hữu của `root`.
- **Thư mục:** Quyền `0755` (`drwxr-xr-x`) — Mọi user có thể đọc/truy cập, chỉ root mới có thể tạo/sửa/xóa.
- **Tệp tin:** Quyền `0644` (`-rw-r–r–`) — Mọi user có thể đọc, chỉ root mới có thể ghi.
> **Lưu ý:** Cả hai file `config.yaml` và `.env` đều là tùy chọn. Nếu không có thư mục `/etc/hermes/`, Hermes sẽ hoạt động bình thường theo cấu hình cấp người dùng.
### Tùy chỉnh đường dẫn Managed Scope (`HERMES_MANAGED_DIR`)
Trong môi trường container (Docker) hoặc khi muốn đặt thư mục chính sách ở vị trí khác:
```bash
export HERMES_MANAGED_DIR=/opt/org/hermes-policy
```
*(Biến môi trường này cần được cố định bởi Admin trong Dockerfile hoặc service unit, tránh để user tùy tiện thay đổi nhằm bypass chính sách).*
-–
## 3. Thứ tự ưu tiên (Precedence Order)
Đối với các khóa (keys) được định nghĩa trong Managed Scope, thứ tự ưu tiên giải quyết cấu hình như sau:
| Thứ tự | Nguồn cấu hình | Mô tả |
| :— | :— | :— |
| **1 (Cao nhất)** | `/etc/hermes/config.yaml` | Cấu hình cấp hệ thống do Admin quản lý |
| **2** | `/etc/hermes/.env` | Biến môi trường cấp hệ thống do Admin quản lý |
| **3** | Shell Environment Variables | Biến môi trường export trong terminal *(Bị Managed Scope ghi đè nếu trùng key)* |
| **4** | `~/.hermes/config.yaml` | Cấu hình cấp người dùng |
| **5 (Thấp nhất)** | `~/.hermes/.env` | Biến môi trường cấp người dùng |
### Nguyên lý gộp cấu hình cấp lá (Leaf-level Merging)
- Việc ghim `model.default` **không** khóa toàn bộ nhóm `model.*`.
- Ví dụ, nếu file `/etc/hermes/config.yaml` chứa:
```yaml
model:
default: org/standard-model
```
Thì chỉ `model.default` bị cố định; người dùng vẫn có thể tự do cấu hình `model.fallback`, `model.temperature`… trong `~/.hermes/config.yaml`.
-–
## 4. Hướng dẫn thiết lập cho Quản trị viên (Admin Setup Guide)
### Bước 1: Tạo thư mục cấu hình hệ thống
```bash
sudo mkdir -p /etc/hermes
```
### Bước 2: Tạo tệp cấu hình `config.yaml`
Ghim các giá trị cấu hình mặc định hoặc các quy tắc bảo mật bắt buộc:
```bash
sudo tee /etc/hermes/config.yaml > /dev/null <<‘YAML’
model:
provider: nous
security:
redact_secrets: true
YAML
```
### Bước 3: (Tùy chọn) Tạo tệp môi trường `.env`
Ghim các thông số môi trường dùng chung (không chứa secrets tối mật cá nhân):
```bash
sudo tee /etc/hermes/.env > /dev/null <<‘ENV’
OPENAI_API_BASE=https://inference.example.com/v1
ENV
```
### Bước 4: Thiết lập quyền truy cập bảo mật
```bash
sudo chmod 0755 /etc/hermes
sudo chmod 0644 /etc/hermes/config.yaml /etc/hermes/.env
```
Cấu hình sẽ tự động có hiệu lực ở lần khởi chạy Hermes tiếp theo.
-–
## 5. Kiểm tra & Giám sát Managed Scope
### 1. Kiểm tra qua Hermes CLI
```bash
# Xem danh sách cấu hình và các key bị ghim (kèm nguồn quản lý)
hermes config
# Báo cáo đường dẫn Managed Dir và số lượng key đã ghim
hermes doctor
```
### 2. Hành vi khi người dùng cố tình thay đổi cấu hình bị ghim
Khi người dùng chạy lệnh sửa đổi key đã được quản lý:
```bash
$ hermes config set model.default my/custom-model
```
**Kết quả phản hồi:**
```text
Cannot set ‘model.default’: it is managed by your administrator (/etc/hermes/config.yaml) and cannot be changed.
```
-–
## 6. Mô hình bảo mật & Giới hạn phiên bản v1 (Security & Limitations)
1. **Phụ thuộc vào quyền POSIX:** Nếu người dùng có quyền `sudo`/`root` hoặc quyền ghi vào `/etc/hermes`, họ có thể can thiệp hoặc vô hiệu hóa Managed Scope.
2. **Quyền đọc của tệp `.env` (`0644`):** File `.env` trong `/etc/hermes/` có quyền đọc công khai cho mọi user cục bộ. Do đó, chỉ dùng file này cho các cấu hình dùng chung (như Base URL, default flags), **không lưu token/secret có độ nhạy cảm cao**.
3. **Phạm vi của tiến trình con (Subprocess):** Managed Scope bảo vệ cấu hình Hermes ở cấp người dùng, nhưng không phải là sandbox tuyệt đối ngăn cản tiến trình con đổi biến môi trường trong shell riêng của agent.
4. **Các tính năng chưa hỗ trợ trong v1 (Dự kiến trong tương lai):**
-
Registry/Policy native riêng cho Windows / macOS.
-
Thư mục cấu hình phân tầng dạng `managed.d/`.
-
Cơ chế ký số và kiểm tra toàn vẹn (Signed / Integrity check).
-
Quản trị thiết bị tập trung từ xa (MDM).