Chuyển tới nội dung chính

Cấu hình

Tất cả các cài đặt được lưu trữ trong thư mục

~/.Hermes/ ` để dễ dàng truy cập.

Cấu trúc thư mục​

~/.Hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.JSON       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

`

## Quản lý cấu hình

`bash
Hermes config              # View current configuration
Hermes config edit         # Open config.yaml in your editor
Hermes config set KEY VAL  # Set a specific value
Hermes config check        # Check for missing options (after updates)
Hermes config migrate      # Interactively add missing options

# Examples:
Hermes config set model Anthropic/Claude-opus-4
Hermes config set terminal.backend Docker
Hermes config set OpenRouter_API_KEY sk-or-...  # Saves to .env

`

:::tip
Lệnh 
`Hermes config set
` tự động định tuyến các giá trị đến đúng tệp - Khóa API được lưu vào 

.env

, mọi thứ khác vào 
`config.yaml

.

:::

## Ưu tiên cấu hình

Cài đặt được giải quyết theo thứ tự sau (ưu tiên cao nhất trước):
1. **Đối số CLI** — ví dụ: 
`Hermes chat --model Anthropic/Claude-sonnet-4
` (ghi đè mỗi lệnh gọi)
2. **

~/.Hermes/config.yaml

** — tệp cấu hình chính cho tất cả cài đặt không bí mật
3. **

~/.Hermes/.env

** — dự phòng cho các biến env; **bắt buộc** đối với thông tin bí mật (khóa API, mã thông báo, mật khẩu)
4. **Mặc định tích hợp** — mặc định an toàn được mã hóa cứng khi không có gì khác được đặt

:::info[Rule of Thumb]
Bí mật (khóa API, mã thông báo bot, mật khẩu) có trong 

.env

. Mọi thứ khác (kiểu máy, phần phụ trợ đầu cuối, cài đặt nén, giới hạn bộ nhớ, bộ công cụ) đều có trong 
`config.yaml

. Khi cả hai đều được đặt, 
`config.yaml
` sẽ thắng đối với cài đặt không bí mật.
:::

## Thay thế biến môi trường

Bạn có thể tham chiếu các biến môi trường trong 
`config.yaml
` bằng cú pháp 

$\{VAR_NAME}

:

``` yaml
auxiliary:
  vision:
    API_key: $\{Google_API_KEY}
    base_url: $\{CUSTOM_VISION_URL}`delegation:
  API_key: $\{DELEGATION_KEY}

`
``Nhiều tham chiếu trong một giá trị duy nhất hoạt động: 
`url: "$\{HOST}:$\{PORT}"

. Nếu biến tham chiếu không được đặt, trình giữ chỗ sẽ được giữ nguyên nguyên văn (

$\{UNDEFINED_VAR}
` vẫn giữ nguyên). Chỉ hỗ trợ cú pháp 

$\{VAR}

 - 

$VAR
` trần không được mở rộng.

Để biết cách thiết lập nhà cung cấp AI (OpenRouter, Anthropic, Copilot, điểm cuối tùy chỉnh, LLM tự lưu trữ, mô hình dự phòng, v.v.), hãy xem [AI Providers](/docs/integrations/providers).

### Nhà cung cấp hết thời gian chờ

Bạn có thể đặt 
`providers.<id.request_timeout_seconds
` cho thời gian chờ yêu cầu trên toàn nhà cung cấp, cùng với 
`providers.<id.models.<model.timeout_seconds
` cho ghi đè dành riêng cho từng kiểu máy. Áp dụng cho máy khách chuyển tiếp chính trên mọi phương tiện vận chuyển (OpenAI-wire, Anthropic gốc, tương thích với Anthropic), chuỗi dự phòng, xây dựng lại sau khi xoay vòng thông tin xác thực và (đối với OpenAI-wire) kwarg hết thời gian chờ theo yêu cầu - vì vậy giá trị được định cấu hình sẽ vượt qua 
`Hermes_API_TIMEOUT
` env var kế thừa.

Bạn cũng có thể đặt 
`providers.<id.stale_timeout_seconds
` cho trình phát hiện cuộc gọi cũ không phát trực tuyến, cùng với 
`providers.<id.models.<model.stale_timeout_seconds
` để ghi đè dành riêng cho kiểu máy. Điều này chiến thắng 
`Hermes_API_CALL_STALE_TIMEOUT
` env var kế thừa.

Việc không đặt các giá trị này sẽ giữ nguyên các giá trị mặc định cũ (
`Hermes_API_TIMEOUT=1800

, 
`Hermes_API_CALL_STALE_TIMEOUT=300

, Anthropic 900 gốc). Hiện chưa được kết nối với AWS Bedrock (cả đường dẫn 
`bedrock_converse
` và AnthropicBedrock SDK đều sử dụng boto3 với cấu hình thời gian chờ riêng). Xem ví dụ nhận xét trong [XPROTECTX114XPROTECTX](https://GitHub.com/NousResearch/Hermes-agent/blob/main/CLI-config.yaml.example).

## Cấu hình phần cuối của terminal

Hermes hỗ trợ bảy chương trình phụ trợ đầu cuối. Mỗi cái xác định nơi các lệnh shell của tác nhân thực sự thực thi - máy cục bộ của bạn, bộ chứa Docker, máy chủ từ xa thông qua SSH, hộp cát đám mây Modal (trực tiếp hoặc thông qua cổng do Nous quản lý), không gian làm việc Daytona, Vercel Sandbox hoặc bộ chứa Singularity/Apptainer.

`YAML
terminal:
  backend: local    # local | Docker | SSH | modal | daytona | vercel_sandbox | singularity
  cwd: "."          # Gateway/cron working directory (CLI always uses launch dir)
  timeout: 180      # Per-command timeout in seconds
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "Docker://nikolaik/Python-nodejs:Python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/Python-nodejs:Python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/Python-nodejs:Python3.11-nodejs20"               # Container image for Daytona backend

`
``Đối với các hộp cát trên đám mây như Modal, Daytona và Vercel Sandbox, 
`container_persistent: true
` có nghĩa là Hermes sẽ cố gắng duy trì trạng thái hệ thống tệp trong quá trình giải trí hộp cát. Nó không hứa hẹn rằng các tiến trình nền, không gian PID hoặc hộp cát trực tiếp tương tự sẽ vẫn chạy sau này.

### Tổng quan về phần cuối

| Phần cuối | Lệnh chạy ở đâu | Cô lập | Tốt nhất cho |
|----------|-------------------|-----------|----------|
| **địa phương** | Máy của bạn trực tiếp | Không có | Phát triển, sử dụng cá nhân |
| **Docker** | Bộ chứa Docker liên tục duy nhất (được chia sẻ trong phiên, 

/new

, tác nhân phụ) | Đầy đủ (không gian tên, thả chữ hoa) | Hộp cát an toàn, CI/CD |
| **suỵt** | Máy chủ từ xa qua SSH | Ranh giới mạng | Nhà phát triển từ xa, phần cứng mạnh mẽ |
| **phương thức** | Hộp cát đám mây phương thức | Đầy đủ (VM đám mây) | Điện toán đám mây phù du, evals |
| **daytona** | Không gian làm việc của Daytona | Đầy đủ (vùng chứa đám mây) | Môi trường phát triển đám mây được quản lý |
| **vercel_sandbox** | Hộp cát Vercel | Đầy đủ (microVM đám mây) | Thực thi trên đám mây với khả năng duy trì hệ thống tệp được hỗ trợ nhanh |
| **điểm kỳ dị** | Thùng chứa Singularity/Apptainer | Không gian tên (--containall) | Cụm HPC, máy dùng chung |

### Phần cuối cục bộ

Mặc định. Các lệnh chạy trực tiếp trên máy của bạn mà không bị cô lập. Không cần thiết lập đặc biệt.

`YAML
terminal:
  backend: local

`

:::warning
Tác nhân có cùng quyền truy cập hệ thống tệp như tài khoản người dùng của bạn. Sử dụng 
`Hermes tools
` để tắt các công cụ bạn không muốn hoặc chuyển sang Docker để tạo hộp cát.

:::

### Phần cuối của Docker

Chạy các lệnh bên trong vùng chứa Docker với tính năng tăng cường bảo mật (loại bỏ tất cả các khả năng, không leo thang đặc quyền, giới hạn PID).

**Vùng chứa liên tục duy nhất, không phải mỗi lệnh.** Hermes bắt đầu MỘT vùng chứa tồn tại lâu dài trong lần sử dụng đầu tiên và định tuyến mọi terminal, tệp và cuộc gọi 
`execute_code
` qua 
`Docker exec
` vào cùng một vùng chứa đó — qua các phiên, 

/new

, 

/reset
` và các tác nhân phụ 
`delegate_task
` — trong suốt thời gian của quy trình Hermes. Các thay đổi về thư mục làm việc, các gói đã cài đặt và tệp trong 

/workspace
` được chuyển từ lệnh gọi công cụ này sang lệnh gọi công cụ tiếp theo, giống như một trình bao cục bộ. Thùng chứa được dừng lại và loại bỏ khi tắt máy. Xem **Vòng đời vùng chứa** bên dưới để biết chi tiết.

``` yaml
terminal:
  backend: Docker
  Docker_image: "nikolaik/Python-nodejs:Python3.11-nodejs20"
  Docker_mount_cwd_to_workspace: false  # Mount launch dir into /workspace
  Docker_run_as_host_user: false   # See "Running container as host user" below
  Docker_forward_env:              # Env vars to forward into container

    - "GitHub_TOKEN"
  Docker_volumes:                  # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro for read-only
  Docker_extra_args:               # Extra flags appended verbatim to 
`Docker run

    - "--gpus=all"
    - "--network=host"

# Resource limits
  container_cpu: 1                 # CPU cores (0 = unlimited)
  container_memory: 5120           # MB (0 = unlimited)
  container_disk: 51200            # MB (requires overlay2 on XFS+pquota)
  container_persistent: true       # Persist /workspace and /root across sessions

`
``**
`terminal.Docker_extra_args

** (cũng có thể ghi đè thông qua 
`TERMINAL_Docker_EXTRA_ARGS='["--gpus=all"]'

) cho phép bạn chuyển các cờ 
`Docker run
` tùy ý mà Hermes không hiển thị dưới dạng khóa hạng nhất — 

--gpus

, 

--network

, 

--add-host

, ghi đè 

--security-opt
` thay thế, v.v. Mỗi mục nhập phải được một chuỗi; danh sách được thêm vào cuối cùng vào lệnh gọi 
`Docker run
` đã được tập hợp để nó có thể ghi đè các giá trị mặc định của Hermes nếu cần. Sử dụng một cách tiết kiệm — các cờ xung đột với việc tăng cường hộp cát (giảm khả năng, 

--user

, giá treo liên kết không gian làm việc) sẽ âm thầm làm suy yếu khả năng cách ly.

**Yêu cầu:** Đã cài đặt và chạy Docker Desktop hoặc Docker Engine. Hermes thăm dò 

$PATH
` cùng với các vị trí cài đặt macOS phổ biến (

/usr/local/bin/Docker

, 

/opt/Homebrew/bin/Docker

, gói ứng dụng Docker Desktop). Podman được hỗ trợ ngay lập tức: đặt 
`Hermes_Docker_BINARY=podman
` (hoặc đường dẫn đầy đủ) để buộc nó khi cả hai được cài đặt.

**Vòng đời của vùng chứa:** Hermes sử dụng lại một vùng chứa tồn tại lâu dài (
`Docker run -d ... sleep 2h

) cho mỗi lệnh gọi terminal và công cụ tệp, trong các phiên, các tác nhân phụ 

/new

, 

/reset
` và 
`delegate_task
` trong suốt vòng đời của quy trình Hermes. Các lệnh chạy qua 
`Docker exec
` với trình bao đăng nhập, do đó, các thay đổi thư mục làm việc, gói đã cài đặt và tệp trong 

/workspace
` đều tồn tại từ lệnh gọi công cụ này sang lệnh gọi công cụ tiếp theo. Vùng chứa bị dừng và bị xóa khi Hermes tắt máy (hoặc khi quá trình quét nhàn rỗi lấy lại nó).

Các tác nhân phụ song song được sinh ra thông qua 
`delegate_task(tasks=[...])
` chia sẻ một vùng chứa này - 
`cd
` đồng thời, các đột biến env và ghi vào cùng một đường dẫn sẽ xung đột. Nếu tác nhân phụ cần một hộp cát biệt lập, tác nhân đó phải đăng ký ghi đè hình ảnh theo mỗi tác vụ thông qua 
`register_task_env_overrides()

, môi trường RL và điểm chuẩn (TerminalBench2, HermesSweEnv, v.v.) tự động thực hiện cho hình ảnh Docker theo tác vụ của chúng.

**Tăng cường bảo mật:**
- 

--cap-drop ALL
` chỉ được thêm lại 
`DAC_OVERRIDE

, 
`CHOWN

, 
`FOWNER

- 

--security-opt no-new-privileges

- 

--pids-limit 256

- Các tmpf có kích thước giới hạn dành cho 

/tmp
` (512MB), 

/var/tmp
` (256MB), 

/run
` (64MB)

**Chuyển tiếp thông tin xác thực:** Các biến env được liệt kê trong 
`Docker_forward_env
` trước tiên được phân giải từ môi trường shell của bạn, sau đó là 

~/.Hermes/.env

. Các kỹ năng cũng có thể khai báo 
`required_environment_variables
` được hợp nhất tự động.

### Phần cuối SSH

Chạy lệnh trên máy chủ từ xa qua SSH. Sử dụng ControlMaster để tái sử dụng kết nối (lưu giữ trong 5 phút không hoạt động). Persistent shell được bật theo mặc định - trạng thái (cwd, env vars) tồn tại qua các lệnh.

``` yaml
terminal:
  backend: SSH
  persistent_shell: true           # Keep a long-lived bash session (default: true)

`
``**Biến môi trường bắt buộc:**

`bash
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

`
``**Tùy chọn:**

| Biến | Mặc định | Mô tả |
|----------|----------|-------------|
| 
`TERMINAL_SSH_PORT
` | 
`22
` | Cổng SSH |
| 
`TERMINAL_SSH_KEY
` | (mặc định hệ thống) | Đường dẫn đến khóa riêng SSH |
| 
`TERMINAL_SSH_PERSISTENT
` | 
`true
` | Kích hoạt shell liên tục |

**Cách hoạt động:** Kết nối ngay từ đầu với 
`BatchMode=yes
` và 
`StrictHostKeyChecking=accept-new

. Lớp vỏ liên tục giữ cho một quy trình 
`bash -l
` duy nhất tồn tại trên máy chủ từ xa, liên lạc qua các tệp tạm thời. Các lệnh cần 
`stdin_data
` hoặc 
`sudo
` sẽ tự động chuyển về chế độ một lần.

### Phần cuối phương thứcChạy các lệnh trong hộp cát đám mây [Modal](https://modal.com). Mỗi tác vụ có một máy ảo riêng biệt với CPU, bộ nhớ và ổ đĩa có thể định cấu hình. Hệ thống tập tin có thể được chụp nhanh/khôi phục qua các phiên.

`YAML
terminal:
  backend: modal
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB (5GB)
  container_disk: 51200            # MB (50GB)
  container_persistent: true       # Snapshot/restore filesystem

`
``**Bắt buộc:** Biến môi trường 
`MODAL_TOKEN_ID

 + 
`MODAL_TOKEN_SECRET
` hoặc tệp cấu hình 

~/.modal.TOML

.

**Kiên trì:** Khi được bật, hệ thống tệp hộp cát sẽ được chụp nhanh khi dọn dẹp và được khôi phục trong phiên tiếp theo. Ảnh chụp nhanh được theo dõi trong 

~/.Hermes/modal_snapshots.JSON

. Điều này bảo toàn trạng thái hệ thống tập tin, không phải các tiến trình trực tiếp, không gian PID hoặc các công việc nền.

**Tệp thông tin xác thực:** Được gắn tự động từ 

~/.Hermes/
` (mã thông báo OAuth, v.v.) và được đồng bộ hóa trước mỗi lệnh.

### Phần cuối của Daytona

Chạy các lệnh trong không gian làm việc được quản lý [Daytona](https://daytona.io). Hỗ trợ dừng/tiếp tục để duy trì.

`YAML
terminal:
  backend: daytona
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB → converted to GiB
  container_disk: 10240            # MB → converted to GiB (max 10 GiB)
  container_persistent: true       # Stop/resume instead of delete

`
``**Bắt buộc:** Biến môi trường 
`DAYTONA_API_KEY

.

**Kiên trì:** Khi được bật, hộp cát sẽ dừng (không bị xóa) khi dọn dẹp và tiếp tục lại trong phiên tiếp theo. Tên hộp cát tuân theo mẫu 
`Hermes-\{task_id}

.

**Giới hạn đĩa:** Daytona thực thi mức tối đa 10 GiB. Các yêu cầu trên đây được giới hạn bằng một cảnh báo.

### Phần cuối của Vercel Sandbox

Chạy các lệnh trong microVM đám mây [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). Hermes sử dụng bề mặt công cụ tập tin và terminal thông thường; không có công cụ đối mặt với mô hình dành riêng cho Vercel.

`YAML
terminal:
  backend: vercel_sandbox
  vercel_runtime: node24          # node24 | node22 | Python3.13
  cwd: /vercel/sandbox            # default workspace root
  container_persistent: true      # Snapshot/restore filesystem
  container_disk: 51200           # Shared default only; custom disk is unsupported

`
``**Yêu cầu cài đặt:** Cài đặt thêm SDK tùy chọn:

`bash
pip install 'Hermes-agent[vercel]'

`
``**Xác thực bắt buộc:** Định cấu hình xác thực mã thông báo truy cập với cả ba 
`VERCEL_TOKEN

, 
`VERCEL_PROJECT_ID
` và 
`VERCEL_TEAM_ID

. Đây là thiết lập được hỗ trợ để triển khai và các quy trình Hermes chạy dài bình thường trên Render, Rail, Docker và các máy chủ tương tự.

Để phát triển cục bộ một lần, Hermes cũng chấp nhận mã thông báo Vercel OIDC có thời gian tồn tại ngắn:

`bash
VERCEL_OIDC_TOKEN="$(vc project token <project-name)" Hermes chat

`
``Từ thư mục dự án Vercel được liên kết, bạn có thể bỏ qua tên dự án:

`bash
VERCEL_OIDC_TOKEN="$(vc project token)" Hermes chat

`
``Mã thông báo OIDC có thời gian tồn tại ngắn và không được sử dụng làm đường dẫn triển khai được ghi lại.

**Thời gian chạy:** 
`terminal.vercel_runtime
` hỗ trợ 
`node24

, 
`node22
` và 
`Python3.13

. Nếu không được đặt, Hermes mặc định là 
`node24

.

**Kiên trì:** Khi 
`container_persistent: true

, Hermes chụp nhanh hệ thống tệp hộp cát trong quá trình dọn dẹp và khôi phục hộp cát sau này cho cùng một tác vụ từ ảnh chụp nhanh đó. Nội dung ảnh chụp nhanh có thể bao gồm thông tin xác thực, kỹ năng và tệp bộ đệm được đồng bộ hóa với Hermes đã được sao chép vào hộp cát. Điều này chỉ bảo tồn trạng thái hệ thống tập tin; nó không bảo toàn danh tính hộp cát trực tiếp, không gian PID, trạng thái shell hoặc các tiến trình nền đang chạy.

**Các lệnh nền:** 
`terminal(background=true)
` sử dụng luồng quy trình nền phi cục bộ chung của Hermes. Bạn có thể sinh ra, thăm dò ý kiến, chờ đợi, xem nhật ký và hủy các tiến trình thông qua công cụ xử lý thông thường trong khi hộp cát vẫn hoạt động. Hermes không cung cấp khả năng khôi phục quy trình tách rời Vercel gốc sau khi dọn dẹp hoặc khởi động lại.

**Kích thước đĩa:** Vercel Sandbox hiện không hỗ trợ núm tài nguyên 
`container_disk
` của Hermes. Không đặt 
`container_disk
` hoặc ở 
`51200
` mặc định được chia sẻ; các giá trị không mặc định không thực hiện được chẩn đoán và tạo chương trình phụ trợ thay vì bị âm thầm bỏ qua.

### Phần cuối đơn lẻ/Apptainer

Chạy các lệnh trong vùng chứa [Singularity/Apptainer](https://apptainer.org). Được thiết kế cho các cụm HPC và máy dùng chung không có Docker.

`YAML
terminal:
  backend: singularity
  singularity_image: "Docker://nikolaik/Python-nodejs:Python3.11-nodejs20"
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB
  container_persistent: true       # Writable overlay persists across sessions

`
``**Yêu cầu:** 
`apptainer
` hoặc 
`singularity
` nhị phân trong 

$PATH

.

**Xử lý hình ảnh:** URL Docker (
`Docker://...

) được tự động chuyển đổi thành tệp SIF và được lưu vào bộ nhớ đệm. Các tệp 

.sif
` hiện có được sử dụng trực tiếp.

**Thư mục cào:** Đã giải quyết theo thứ tự: 
`TERMINAL_SCRATCH_DIR
` → 
`TERMINAL_SANDBOX_DIR/singularity
` → 

/scratch/$USER/Hermes-agent
` (quy ước HPC) → 

~/.Hermes/sandboxes/singularity

.

**Cách ly:** Sử dụng 

`
--containall --no-home
` để cách ly không gian tên đầy đủ mà không cần gắn thư mục chính của máy chủ.

### Các vấn đề thường gặp về phần cuối của terminal

Nếu các lệnh đầu cuối bị lỗi ngay lập tức hoặc công cụ đầu cuối được báo cáo là bị vô hiệu hóa:- **Địa phương** — Không có yêu cầu đặc biệt. Mặc định an toàn nhất khi bắt đầu.
- **Docker** — Chạy 
`Docker version
` để xác minh Docker đang hoạt động. Nếu không thành công, hãy sửa Docker hoặc 
`Hermes config set terminal.backend local

.
- **SSH** — Phải đặt cả 
`TERMINAL_SSH_HOST
` và 
`TERMINAL_SSH_USER

. Hermes ghi lại một lỗi rõ ràng nếu thiếu một trong hai.
- **Phương thức** — Cần 
`MODAL_TOKEN_ID
` env var hoặc 

~/.modal.TOML

. Chạy 
`Hermes doctor
` để kiểm tra.
- **Daytona** — Cần 
`DAYTONA_API_KEY

. SDK Daytona xử lý cấu hình URL máy chủ.
- **Điểm kỳ dị** — Cần 
`apptainer
` hoặc 
`singularity
` trong 

$PATH

. Phổ biến trên các cụm HPC.

Khi nghi ngờ, hãy đặt 
`terminal.backend
` trở lại 
`local
` và xác minh rằng các lệnh chạy ở đó trước.

### Đồng bộ hóa tệp từ xa đến máy chủ khi Teardown

Đối với các chương trình phụ trợ **SSH**, **Modal** và **Daytona** (bất cứ nơi nào cây làm việc của tác nhân nằm trên một máy khác với máy chủ đang chạy Hermes), Hermes theo dõi các tệp mà tác nhân đã chạm vào bên trong hộp cát từ xa và khi phân tách phiên/dọn dẹp hộp cát, **đồng bộ hóa các tệp đã sửa đổi trở lại máy chủ** trong 

~/.Hermes/cache/remote-syncs/``<session-id>``/

.
- Kích hoạt khi: đóng phiên, 

/new

, 

/reset

, hết thời gian chờ thông báo cổng, hoàn thành tác nhân phụ 
`delegate_task
` khi trẻ sử dụng chương trình phụ trợ từ xa.
- Bao gồm toàn bộ cây mà tác nhân đã sửa đổi, không chỉ các tệp được mở một cách rõ ràng. Các bổ sung, chỉnh sửa và xóa đều được ghi lại.
- Hộp cát từ xa có thể đã bị hỏng khi bạn đi tìm; bản sao 

~/.Hermes/cache/remote-syncs/…
` cục bộ là bản ghi chính thức về những gì tác nhân đã thay đổi.
- Đầu ra nhị phân lớn (điểm kiểm tra mô hình, tập dữ liệu thô) bị giới hạn theo kích thước — đồng bộ hóa bỏ qua các tệp trên 
`file_sync_max_mb
` (
`100
` mặc định). Hãy tăng tốc nếu bạn mong đợi những hiện vật lớn hơn sẽ quay trở lại.

``` yaml
terminal:
  file_sync_max_mb: 100     # default — sync files up to 100 MB each
  file_sync_enabled: true   # default — set false to skip the sync entirely

`
``Đây là cách bạn khôi phục kết quả từ các hộp cát đám mây tạm thời bị hủy sau khi phiên kết thúc mà không cần phải thông báo rõ ràng cho tổng đài viên 
`scp
` hoặc 
`modal volume put
` mọi tạo phẩm.

### Gắn kết khối lượng Docker

Khi sử dụng chương trình phụ trợ Docker, 
`Docker_volumes
` cho phép bạn chia sẻ các thư mục máy chủ với vùng chứa. Mỗi mục sử dụng cú pháp Docker 

`
-v
` tiêu chuẩn: 
`host_path:container_path[:options]

.

``` yaml
terminal:
  backend: Docker
  Docker_volumes:

    - "/home/user/projects:/workspace/projects"   # Read-write (default)
    - "/home/user/datasets:/data:ro"              # Read-only
    - "/home/user/.Hermes/cache/documents:/output" # Gateway-visible exports

`
``Điều này hữu ích cho:
- **Cung cấp tệp** cho đại lý (bộ dữ liệu, cấu hình, mã tham chiếu)
- **Nhận file** từ đại lý (mã được tạo, báo cáo, xuất)
- **Không gian làm việc chung** nơi cả bạn và nhân viên đều truy cập vào cùng một tệp

Nếu bạn sử dụng cổng nhắn tin và muốn tác nhân gửi các tệp được tạo qua
`MEDIA:/...

, thích một giá đỡ xuất khẩu có thể nhìn thấy trên máy chủ chuyên dụng như

/home/user/.Hermes/cache/documents:/output

.
- Ghi file bên trong Docker vào 

/output/...

- Phát ra **đường dẫn máy chủ** trong 
`MEDIA:

, ví dụ:

MEDIA:/home/user/.Hermes/cache/documents/report.txt

- **không** phát ra 

/workspace/...
` hoặc 

/output/...
` trừ khi đường dẫn chính xác đó cũng
  tồn tại cho quá trình cổng trên máy chủ

:::warning
Các khóa trùng lặp YAML âm thầm ghi đè các khóa trước đó. Nếu bạn đã có một
Khối 
`Docker_volumes:

, hợp nhất các mount mới vào cùng danh sách thay vì thêm
một khóa 
`Docker_volumes:
` khác ở sau trong tệp.
:::

Cũng có thể được đặt thông qua biến môi trường: 
`TERMINAL_Docker_VOLUMES='["/host:/container"]'
` (mảng JSON).

### Chuyển tiếp thông tin xác thực Docker

Theo mặc định, các phiên đầu cuối Docker không kế thừa thông tin xác thực máy chủ tùy ý. Nếu bạn cần một mã thông báo cụ thể bên trong vùng chứa, hãy thêm nó vào 
`terminal.Docker_forward_env

.

``` yaml
terminal:
  backend: Docker
  Docker_forward_env:

    - "GitHub_TOKEN"
    - "npm_TOKEN"

`
``Hermes phân giải từng biến được liệt kê từ shell hiện tại của bạn trước tiên, sau đó quay trở lại 

~/.Hermes/.env
` nếu nó được lưu bằng 
`Hermes config set

.

:::warning
Mọi thứ được liệt kê trong 
`Docker_forward_env
` sẽ hiển thị với các lệnh chạy bên trong vùng chứa. Chỉ chuyển tiếp thông tin xác thực mà bạn cảm thấy thoải mái khi hiển thị trong phiên cuối.
:::

### Chạy vùng chứa với tư cách là người dùng máy chủ của bạn

Theo mặc định, các vùng chứa Docker chạy dưới dạng 
`root
` (UID 0). Các tệp được tạo bên trong 

/workspace
` hoặc các liên kết gắn kết khác cuối cùng thuộc quyền sở hữu của root trên máy chủ, vì vậy sau một phiên, bạn phải 
`sudo chown
` chúng trước khi có thể chỉnh sửa chúng từ trình chỉnh sửa máy chủ của mình. Cờ 
`terminal.Docker_run_as_host_user
` sửa lỗi này:

``` yaml
terminal:
  backend: Docker
  Docker_run_as_host_user: true   # default: false

`
`Khi được bật, Hermes sẽ gắn 

`
--user $(id -u):$(id -g)
` vào lệnh 
`Docker run
` để các tệp được ghi vào thư mục được gắn liên kết (

/workspace

, 

/root

, mọi thứ trong 
`Docker_volumes

) đều thuộc quyền sở hữu của người dùng máy chủ của bạn chứ không phải root. Sự đánh đổi: vùng chứa không còn có thể 
`apt install
` hoặc ghi vào các đường dẫn thuộc sở hữu gốc như 

/root/.npm

 - sử dụng hình ảnh cơ sở có 
`HOME
` thuộc sở hữu của người dùng không phải root (hoặc thêm công cụ cần thiết của bạn vào thời gian xây dựng hình ảnh) nếu bạn cần cả hai.

Để 
`false
` này (mặc định) để có hành vi tương thích ngược. Hãy bật nó lên khi quy trình làm việc của bạn chủ yếu là "chỉnh sửa các tệp máy chủ được gắn" và bạn cảm thấy mệt mỏi với 
`sudo chown -R

.

### Tùy chọn: Gắn thư mục khởi chạy vào 

/workspace
``Các hộp cát Docker được cách ly theo mặc định. Hermes **không** chuyển thư mục làm việc trên máy chủ hiện tại của bạn vào vùng chứa trừ khi bạn chọn tham gia một cách rõ ràng.

Kích hoạt nó trong 
`config.yaml

:

``` yaml
terminal:
  backend: Docker
  Docker_mount_cwd_to_workspace: true

`
``Khi được kích hoạt:

- nếu bạn khởi chạy Hermes từ 

~/projects/my-app

, thư mục máy chủ đó sẽ được gắn kết với 

/workspace

- chương trình phụ trợ Docker bắt đầu trong 

/workspace

- cả công cụ tập tin và lệnh đầu cuối đều nhìn thấy cùng một dự án được gắn kết

Khi bị vô hiệu hóa, 

/workspace
` vẫn thuộc sở hữu của hộp cát trừ khi bạn gắn kết thứ gì đó một cách rõ ràng thông qua 
`Docker_volumes

.

Đánh đổi an ninh:
- 
`false
` bảo toàn ranh giới hộp cát
- 
`true
` cung cấp cho hộp cát quyền truy cập trực tiếp vào thư mục mà bạn đã khởi chạy Hermes từ đó

Chỉ sử dụng tùy chọn tham gia khi bạn cố tình muốn vùng chứa hoạt động trên các tệp máy chủ trực tiếp.

### Vỏ liên tục

Theo mặc định, mỗi lệnh đầu cuối chạy trong quy trình con riêng của nó - thư mục làm việc, biến môi trường và biến shell được đặt lại giữa các lệnh. Khi **persistent shell** được bật, một quy trình bash tồn tại lâu dài sẽ được duy trì trong các lệnh gọi 
`execute()
` để trạng thái đó tồn tại giữa các lệnh.

Điều này hữu ích nhất cho **phụ trợ SSH**, trong đó nó cũng loại bỏ chi phí kết nối theo lệnh. Persistent shell được **bật theo mặc định cho SSH** và bị vô hiệu hóa cho chương trình phụ trợ cục bộ.

``` yaml
terminal:
  persistent_shell: true   # default — enables persistent shell for SSH

`
``Để vô hiệu hóa:

`bash
Hermes config set terminal.persistent_shell false

`
``**Điều gì vẫn tồn tại qua các lệnh:**

- Thư mục làm việc (
`cd /tmp
` cho lệnh tiếp theo)
- Các biến môi trường đã xuất (
`export FOO=bar

)
- Biến Shell (
`MY_VAR=hello

)

**Ưu tiên:**

| Cấp độ | Biến | Mặc định |
|-------|----------|---------|
| Cấu hình |

terminal.persistent_shell
` | 
`true
` |
| Ghi đè SSH |

TERMINAL_SSH_PERSISTENT
` | theo cấu hình |
| Ghi đè cục bộ |

TERMINAL_LOCAL_PERSISTENT
` | 
`false
` |

Các biến môi trường trên mỗi chương trình phụ trợ được ưu tiên cao nhất. Nếu bạn cũng muốn có Shell liên tục trên chương trình phụ trợ cục bộ:

``` bash
 export TERMINAL_LOCAL_PERSISTENT=true

`

:::note
Các lệnh yêu cầu 
`stdin_data
` hoặc sudo sẽ tự động quay trở lại chế độ một lần, vì stdin của shell liên tục đã bị giao thức IPC chiếm giữ.

:::

Xem [Code Execution](features/code-execution.md) và [Terminal section of the README](features/tools.md) để biết chi tiết về từng chương trình phụ trợ.

## Cài đặt kỹ năng

Các kỹ năng có thể khai báo cài đặt cấu hình của riêng mình thông qua bảng điều khiển SKILL.md. Đây là các giá trị không bí mật (đường dẫn, tùy chọn, cài đặt miền) được lưu trữ trong không gian tên 
`skills.config
` trong 
`config.yaml

.

``` yaml
skills:
  config:
    myplugin:
      path: ~/myplugin-data   # Example — each skill defines its own keys

`
``**Cách cài đặt kỹ năng hoạt động:**
- 
`Hermes config migrate
` quét tất cả các kỹ năng đã bật, tìm các cài đặt chưa được định cấu hình và đề nghị nhắc bạn

- 
`Hermes config show
` hiển thị tất cả cài đặt kỹ năng trong "Cài đặt kỹ năng" với kỹ năng mà chúng thuộc về
- Khi một kỹ năng được tải, các giá trị cấu hình đã giải quyết của nó sẽ tự động được đưa vào bối cảnh kỹ năng`**Đặt giá trị theo cách thủ công:**

``` bash
Hermes config set skills.config.myplugin.path ~/myplugin-data

`
``Để biết chi tiết về cách khai báo cài đặt cấu hình trong kỹ năng của bạn, hãy xem [Creating Skills — Config Settings](/docs/developer-guide/creating-skills#config-settings-configYAML).

### Bảo vệ việc ghi kỹ năng do tác nhân tạo

Khi tác nhân sử dụng 
`skill_manage
` để tạo, chỉnh sửa, vá hoặc xóa một kỹ năng, Hermes có thể tùy ý quét nội dung mới/cập nhật để tìm các mẫu từ khóa nguy hiểm (thu thập thông tin xác thực, chèn lời nhắc rõ ràng, hướng dẫn exfil). Máy quét **tắt theo mặc định** — các quy trình làm việc của tác nhân thực chạm vào 

~/.SSH/
` hoặc đề cập đến 

$OpenAI_API_KEY
` thường xuyên vấp phải phương pháp phỏng đoán. Bật lại nếu bạn muốn máy quét nhắc bạn trước khi kỹ năng của đặc vụ ghi đất:

`YAML
skills:
  guard_agent_created: true   # default: false

`
`Khi được bật, mọi bề mặt 
`skill_manage
` được gắn cờ sẽ ghi vào dưới dạng lời nhắc phê duyệt với lý do căn bản của máy quét. Chấp nhận viết đất; việc ghi bị từ chối trả lại một lỗi giải thích cho tác nhân.

## Cấu hình bộ nhớ

`YAML
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

`

## An toàn khi đọc tệp

Kiểm soát lượng nội dung mà một cuộc gọi 
`read_file
` có thể trả về. Các lần đọc vượt quá giới hạn sẽ bị từ chối kèm theo lỗi yêu cầu tác nhân sử dụng 
`offset
` và 
`limit
` cho phạm vi nhỏ hơn. Điều này ngăn không cho một lần đọc gói JS được rút gọn hoặc tệp dữ liệu lớn tràn ngập cửa sổ ngữ cảnh.

`YAML
file_read_max_chars: 100000  # default — ~25-35K tokens

`
``Hãy tăng nó nếu bạn đang sử dụng mô hình có cửa sổ ngữ cảnh lớn và thường xuyên đọc các tệp lớn. Hạ thấp nó cho các mô hình ngữ cảnh nhỏ để duy trì hiệu quả đọc:

`YAML

# Large context model (200K+)
file_read_max_chars: 200000

# Small local model (16K context)
file_read_max_chars: 30000

`
``Tác nhân cũng tự động loại bỏ các lần đọc tệp trùng lặp — nếu cùng một vùng tệp được đọc hai lần và tệp không thay đổi, một đoạn sơ khai nhẹ sẽ được trả về thay vì gửi lại nội dung. Thao tác này sẽ đặt lại tính năng nén ngữ cảnh để tác nhân có thể đọc lại các tệp sau khi nội dung của chúng được tóm tắt.

## Giới hạn cắt ngắn đầu ra của công cụ

Ba giới hạn liên quan kiểm soát số lượng đầu ra thô mà một công cụ có thể trả lại trước khi Hermes cắt bớt nó:

``` yaml
tool_output:
  max_bytes: 50000        # terminal output cap (chars)
  max_lines: 2000         # read_file pagination cap
  max_line_length: 2000   # per-line cap in read_file's line-numbered view

`

- **
`max_bytes

`
** — Khi lệnh 
`terminal
` tạo ra nhiều hơn số ký tự này của thiết bị xuất chuẩn/thiết bị xuất chuẩn kết hợp, Hermes giữ lại 40% đầu tiên và 60% cuối cùng và chèn thông báo 

[OUTPUT TRUNCATED]
` giữa chúng. 
`50000
` mặc định (≈12-15K mã thông báo trên các mã thông báo thông thường).
- **
`max_lines

** — Giới hạn trên của tham số 
`limit
` của một lệnh gọi 
`read_file

. Các yêu cầu ở trên được giới hạn để một lần đọc không thể tràn ngập cửa sổ ngữ cảnh. 
`2000
` mặc định.
- **
`max_line_length

** — Giới hạn mỗi dòng được áp dụng khi 
`read_file
` phát ra chế độ xem đánh số dòng. Các dòng dài hơn dòng này sẽ được cắt ngắn thành nhiều ký tự, theo sau là 

... [truncated]

. 
`2000
` mặc định.

Tăng giới hạn đối với các mô hình có cửa sổ ngữ cảnh lớn có thể cung cấp nhiều đầu ra thô hơn cho mỗi lệnh gọi. Giảm chúng cho các mô hình ngữ cảnh nhỏ để giữ kết quả công cụ nhỏ gọn:

``` yaml

# Large context model (200K+)
tool_output:
  max_bytes: 150000
  max_lines: 5000

# Small local model (16K context)
tool_output:
  max_bytes: 20000
  max_lines: 500

`

## Tắt bộ công cụ toàn cầu

Để ngăn chặn các bộ công cụ cụ thể trên CLI và mọi nền tảng cổng vào trong một
đặt, liệt kê tên của họ theo 
`agent.disabled_toolsets

:

``` yaml
agent:
  disabled_toolsets:

    - memory       # hide memory tools + MEMORY_GUIDANCE injection
    - web          # no web_search / web_extract anywhere

`
``Điều này áp dụng **sau** cấu hình công cụ trên mỗi nền tảng (
`platform_toolsets
` được viết bởi
`Hermes tools

), do đó, bộ công cụ được liệt kê ở đây luôn bị xóa — ngay cả khi
cấu hình đã lưu của nền tảng vẫn liệt kê nó. Sử dụng cái này khi bạn muốn một cái
chuyển sang "tắt X ở mọi nơi" thay vì chỉnh sửa hơn 15 hàng nền tảng trong
giao diện người dùng 
`Hermes tools

.

Để trống danh sách hoặc bỏ sót khóa là điều không nên làm.

## Cách ly cây công việc Git

Kích hoạt cây công việc git riêng biệt để chạy song song nhiều tác nhân trên cùng một repo:

``` yaml
worktree: true    # Always create a worktree (same as Hermes -w)

# worktree: false # Default — only when -w flag is passed

`
``Khi được bật, mỗi phiên CLI sẽ tạo một cây làm việc mới trong 

.worktrees/
` với nhánh riêng. Các đại lý có thể chỉnh sửa tệp, cam kết, đẩy và tạo PR mà không can thiệp lẫn nhau. Bàn làm việc sạch sẽ được dỡ bỏ khi thoát ra; những cái bẩn được giữ lại để phục hồi thủ công.

Bạn cũng có thể liệt kê các tệp được gitignored để sao chép vào cây làm việc thông qua 

.worktreeinclude
` trong thư mục gốc repo của mình:

`
# .worktreeinclude
.env
.venv/
node_modules/

`

## Nén ngữ cảnh

Hermes tự động nén các cuộc hội thoại dài để nằm trong cửa sổ ngữ cảnh của mô hình của bạn. Trình tóm tắt nén là một lệnh gọi LLM riêng biệt — bạn có thể trỏ nó tới bất kỳ nhà cung cấp hoặc điểm cuối nào.

Tất cả cài đặt nén đều có trong 
`config.yaml
` (không có biến môi trường).

### Tham khảo đầy đủ

``` yaml
compression:
  enabled: true                                     # Toggle compression on/off
  threshold: 0.50                                   # Compress at this % of context limit
  target_ratio: 0.20                                # Fraction of threshold to preserve as recent tail
  protect_last_n: 20                                # Min recent messages to keep uncompressed
  hygiene_hard_message_limit: 400                   # Gateway safety valve — see below

# The summarization model/provider is configured under auxiliary:
auxiliary:
  compression:
    model: ""                                       # Empty = use main chat model. Override with e.g. "Google/Gemini-3-flash-preview" for cheaper/faster compression.
    provider: "auto"                                # Provider: "auto", "OpenRouter", "nous", "Codex", "main", etc.
    base_url: null                                  # Custom OpenAI-compatible endpoint (overrides provider)

`

:::info[Legacy config migration]
Các cấu hình cũ hơn với 
`compression.summary_model

, 
`compression.summary_provider
` và 
`compression.summary_base_url
` được tự động di chuyển sang 
`auxiliary.compression.*
` trong lần tải đầu tiên (phiên bản cấu hình 17). Không cần thao tác thủ công.

:::

hygiene_hard_message_limit
` là **van an toàn nén trước** chỉ dành cho cổng. Các phiên chạy nhanh với hàng nghìn thông báo có thể đạt đến giới hạn ngữ cảnh của mô hình trước khi kích hoạt ngưỡng phần trăm ngữ cảnh thông thường; khi số lượng tin nhắn vượt quá mức trần này, Hermes buộc phải nén bất kể việc sử dụng mã thông báo như thế nào. 
`400
` mặc định - tăng nó cho các nền tảng có phiên rất dài là bình thường, hạ thấp nó xuống để buộc nén mạnh hơn. Việc chỉnh sửa giá trị này trên một cổng đang chạy sẽ có hiệu lực đối với thông báo tiếp theo (xem bên dưới).:::tip Gateway hot-reload of compression and context length
Kể từ các bản phát hành gần đây, việc chỉnh sửa 
`model.context_length
` hoặc bất kỳ khóa 
`compression.*
` nào trong 
`config.yaml
` trên một cổng đang chạy sẽ có hiệu lực đối với thông báo tiếp theo — không cần khởi động lại cổng, không cần 

/reset

, không cần xoay phiên. Chữ ký tác nhân được lưu trong bộ nhớ đệm bao gồm các khóa này, do đó, cổng sẽ xây dựng lại tác nhân một cách minh bạch khi thấy có thay đổi. Khóa API và cấu hình công cụ/kỹ năng vẫn yêu cầu đường dẫn tải lại thông thường.
:::

### Các thiết lập phổ biến`**Mặc định (tự động phát hiện) — không cần cấu hình:**

`
``` yaml
compression:
  enabled: true
  threshold: 0.50

`

Sử dụng nhà cung cấp chính và mô hình chính của bạn. Ghi đè theo từng tác vụ (ví dụ: 
`auxiliary.compression.provider: OpenRouter

 + 
`model: Google/Gemini-2.5-flash

) nếu bạn muốn nén trên mô hình rẻ hơn mô hình trò chuyện chính của mình.

**Bắt buộc một nhà cung cấp cụ thể** (dựa trên OAuth hoặc khóa API):

`
`YAML
auxiliary:
  compression:
    provider: nous
    model: Gemini-3-flash

`

Hoạt động với bất kỳ nhà cung cấp nào: 
`nous

, 
`OpenRouter

, 
`Codex

, 
`Anthropic

, 
`main

, v.v.

**Custom Endpoint** (tự lưu trữ, OLlama, zai, DeepSeek, v.v.):

`
`YAML
auxiliary:
  compression:
    model: glm-4.7
    base_url: https://API.Z.AI/API/coding/paas/v4

`

Trỏ vào điểm cuối tương thích với OpenAI tùy chỉnh. Sử dụng 
`OpenAI_API_KEY
` để xác thực.

### Cách ba nút tương tác`| 
`auxiliary.compression.provider
` | 
`auxiliary.compression.base_url
` | Kết quả |
|----------------------|----------------------|--------|
| 
`auto
` (mặc định) | chưa được đặt | Tự động phát hiện nhà cung cấp tốt nhất hiện có |
| 
`nous
` / 
`OpenRouter
` / v.v. | chưa được đặt | Buộc nhà cung cấp đó sử dụng xác thực của nó |
| bất kỳ | đặt | Sử dụng trực tiếp điểm cuối tùy chỉnh (nhà cung cấp bị bỏ qua) |

:::warning[Summary model context length requirement]
Mô hình tóm tắt **phải** có cửa sổ ngữ cảnh ít nhất lớn bằng mô hình tác nhân chính của bạn. Trình nén gửi toàn bộ phần giữa của cuộc hội thoại đến mô hình tóm tắt — nếu cửa sổ ngữ cảnh của mô hình đó nhỏ hơn cửa sổ ngữ cảnh của mô hình chính thì lệnh gọi tóm tắt sẽ không thành công do lỗi độ dài ngữ cảnh. Khi điều này xảy ra, các lượt ở giữa sẽ **bị bỏ mà không có phần tóm tắt**, làm mất đi bối cảnh cuộc trò chuyện trong im lặng. Nếu bạn ghi đè mô hình, hãy xác minh độ dài ngữ cảnh của nó đáp ứng hoặc vượt quá mô hình chính của bạn.

:::

## Công cụ bối cảnh

Công cụ ngữ cảnh kiểm soát cách quản lý các cuộc hội thoại khi đạt đến giới hạn mã thông báo của mô hình. Công cụ 
`compressor
` tích hợp sử dụng tính năng tóm tắt mất dữ liệu (xem [Context Compression](/docs/developer-guide/context-compression-and-caching)). Công cụ plugin có thể thay thế nó bằng các chiến lược thay thế.

``` yaml
context:
  engine: "compressor"    # default — built-in lossy summarization

`
``Để sử dụng công cụ plugin (ví dụ: LCM để quản lý bối cảnh không mất dữ liệu):

`YAML
context:
  engine: "lcm"          # must match the plugin's name

`
``Công cụ plugin **không bao giờ được kích hoạt tự động** — bạn phải đặt rõ ràng 
`context.engine
` cho tên plugin. Các công cụ có sẵn có thể được duyệt và chọn thông qua 
`Hermes plugins
` → Plugin nhà cung cấp → Công cụ bối cảnh.

Xem [Memory Providers](/docs/user-guide/features/memory-providers) để biết hệ thống chọn một lần tương tự dành cho các plugin bộ nhớ.

## Áp lực ngân sách lặp lại

Khi tác nhân đang thực hiện một nhiệm vụ phức tạp với nhiều lệnh gọi công cụ, nó có thể đốt hết ngân sách lặp lại của mình (mặc định: 90 lượt) mà không nhận ra rằng nó sắp hết. Áp lực ngân sách sẽ tự động cảnh báo mô hình khi nó đạt đến giới hạn:

| Ngưỡng | Cấp độ | Người mẫu nhìn thấy gì |
|----------|-------|-------|----------------------|
| **70%** | Thận trọng |

[BUDGET: 63/90. 27 iterations left. Start consolidating.]
` |
| **90%** | Cảnh báo |

[BUDGET WARNING: 81/90. Only 9 left. Respond NOW.]
` |

Cảnh báo được đưa vào JSON của kết quả công cụ cuối cùng (dưới dạng trường 
`_budget_warning

) thay vì dưới dạng các thông báo riêng biệt — điều này sẽ duy trì bộ nhớ đệm nhanh chóng và không làm gián đoạn cấu trúc hội thoại.

`YAML
agent:
  max_turns: 90                # Max iterations per conversation turn (default: 90)
  API_max_retries: 3           # Retries per provider before fallback engages (default: 3)

`
``Áp lực ngân sách được bật theo mặc định. Tác nhân xem các cảnh báo một cách tự nhiên như một phần kết quả của công cụ, khuyến khích nó củng cố công việc của mình và đưa ra phản hồi trước khi hết số lần lặp.

Khi ngân sách lặp lại đã cạn kiệt hoàn toàn, CLI sẽ hiển thị thông báo cho người dùng: 

⚠ Iteration budget reached (90/90) — response may be incomplete

. Nếu ngân sách cạn kiệt trong quá trình làm việc đang diễn ra, tổng đài viên sẽ tạo một bản tóm tắt về những gì đã hoàn thành trước khi dừng lại.

agent.API_max_retries
` kiểm soát số lần Hermes thử lại lệnh gọi API của nhà cung cấp khi có lỗi tạm thời (giới hạn tốc độ, rớt kết nối, 5xx) **trước khi** chuyển đổi nhà cung cấp dự phòng bắt đầu. Mặc định là 
`3
` — tổng cộng bốn lần thử. Nếu bạn đã định cấu hình [fallback providers](/docs/user-guide/features/fallback-providers) và muốn khắc phục lỗi nhanh hơn, hãy thả lỗi này xuống 
`0
` để lỗi tạm thời đầu tiên trên chính của bạn ngay lập tức được chuyển sang dự phòng thay vì liên tục thử lại đối với điểm cuối không ổn định.

### Hết thời gian chờ APIHermes có các lớp thời gian chờ riêng biệt để phát trực tuyến, cộng với một trình phát hiện lỗi thời cho các cuộc gọi không phát trực tuyến. Trình phát hiện lỗi cũ chỉ tự động điều chỉnh cho các nhà cung cấp địa phương khi bạn để chúng ở chế độ mặc định ngầm định.

| Hết giờ | Mặc định | Nhà cung cấp địa phương | Cấu hình/env |
|----------|----------|-------|--------------|
| Hết thời gian đọc ổ cắm | 120s | Tự động nâng lên những năm 1800 |

Hermes_STREAM_READ_TIMEOUT
` |
| Phát hiện luồng cũ | thập niên 180 | Tự động tắt |

Hermes_STREAM_STALE_TIMEOUT
` |
| Phát hiện không phát trực tuyến cũ | 300 giây | Tự động tắt khi để ẩn |

providers.<id.stale_timeout_seconds
` hoặc 
`Hermes_API_CALL_STALE_TIMEOUT
` |
| Cuộc gọi API (không phát trực tuyến) | Những năm 1800 | Không thay đổi |

providers.<id.request_timeout_seconds
` / 
`timeout_seconds
` hoặc 
`Hermes_API_TIMEOUT
` |`**Thời gian chờ đọc ổ cắm** kiểm soát khoảng thời gian httpx chờ đoạn dữ liệu tiếp theo từ nhà cung cấp. LLM cục bộ có thể mất vài phút để điền trước vào bối cảnh lớn trước khi tạo mã thông báo đầu tiên, vì vậy Hermes tăng thời gian này lên 30 phút khi phát hiện điểm cuối cục bộ. Nếu bạn đặt rõ ràng 
`Hermes_STREAM_READ_TIMEOUT

, giá trị đó luôn được sử dụng bất kể phát hiện điểm cuối.

**Phát hiện luồng cũ** sẽ tắt các kết nối nhận ping duy trì SSE nhưng không có nội dung thực tế. Tính năng này bị vô hiệu hóa hoàn toàn đối với các nhà cung cấp địa phương vì họ không gửi ping duy trì trong quá trình điền trước.

**Tính năng phát hiện không phát trực tuyến cũ** sẽ loại bỏ các cuộc gọi không phát trực tuyến không tạo ra phản hồi quá lâu. Theo mặc định, Hermes vô hiệu hóa tính năng này trên các điểm cuối cục bộ để tránh kết quả dương tính giả trong quá trình điền trước kéo dài. Nếu bạn đặt rõ ràng 
`providers.<id.stale_timeout_seconds

, 
`providers.<id.models.<model.stale_timeout_seconds
` hoặc 
`Hermes_API_CALL_STALE_TIMEOUT

, giá trị rõ ràng đó sẽ được tôn trọng ngay cả trên các điểm cuối cục bộ.

## Cảnh báo áp lực bối cảnh

Tách biệt khỏi áp lực ngân sách lặp lại, áp lực ngữ cảnh theo dõi mức độ tiến gần của cuộc hội thoại đến **ngưỡng nén** — điểm mà tính năng nén ngữ cảnh kích hoạt để tóm tắt các tin nhắn cũ hơn. Điều này giúp cả bạn và nhân viên hiểu được khi nào cuộc trò chuyện sẽ kéo dài.

| Tiến độ | Cấp độ | Chuyện gì xảy ra |
|----------|-------|-------------|
| ** ≥ 60%** đến ngưỡng | Thông tin | CLI hiển thị thanh tiến trình màu lục lam; cổng gửi thông báo thông tin |
| ** ≥ 85%** đến ngưỡng | Cảnh báo | CLI hiển thị thanh màu vàng đậm; cổng cảnh báo việc nén sắp xảy ra |

Trong CLI, áp lực ngữ cảnh xuất hiện dưới dạng thanh tiến trình trong nguồn cấp dữ liệu đầu ra của công cụ:

`
  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

`
``Trên nền tảng nhắn tin, một thông báo bằng văn bản đơn giản sẽ được gửi:

`
◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

`
``Nếu tính năng tự động nén bị tắt, thay vào đó, cảnh báo sẽ cho bạn biết ngữ cảnh có thể bị cắt bớt.

Áp lực bối cảnh là tự động - không cần cấu hình. Nó kích hoạt hoàn toàn dưới dạng thông báo hướng tới người dùng và không sửa đổi luồng tin nhắn hoặc đưa bất kỳ thứ gì vào ngữ cảnh của mô hình.

## Chiến lược nhóm thông tin xác thực

Khi bạn có nhiều khóa API hoặc mã thông báo OAuth cho cùng một nhà cung cấp, hãy định cấu hình chiến lược xoay vòng:

`YAML
credential_pool_strategies:
  OpenRouter: round_robin    # cycle through keys evenly
  Anthropic: least_used      # always pick the least-used key

`
``Tùy chọn: 
`fill_first
` (mặc định), 
`round_robin

, 
`least_used

, 
`random

. Xem [Credential Pools](/docs/user-guide/features/credential-pools) để biết tài liệu đầy đủ.

## Bộ nhớ đệm nhắc nhở

Hermes tự động bật bộ nhớ đệm nhắc nhở giữa các phiên khi nhà cung cấp hoạt động hỗ trợ nó — không cần cấu hình người dùng.

Đối với Claude trên **native Anthropic**, **OpenRouter** và **Nous Portal**, Hermes gắn các điểm dừng 
`cache_control
` với TTL 1 giờ (
`ttl: "1h"

) trên lời nhắc hệ thống và các khối kỹ năng. Lần gửi đầu tiên trong vòng một giờ mới sẽ thanh toán đầy đủ phí đầu vào; các lần gửi tiếp theo qua bất kỳ phiên nào trong cùng một giờ sẽ được lấy từ bộ đệm với tốc độ đọc bộ đệm được chiết khấu. Điều này có nghĩa là lời nhắc hệ thống, nội dung kỹ năng được tải và phần đầu của bất kỳ bối cảnh dài nào bao gồm sẽ được sử dụng lại trong các phiên 
`Hermes
` và trên các tác nhân phụ được phân nhánh trong giờ đầu tiên.

Đám mây Qwen (Alibaba DashScope) giới hạn lưu trữ TTL ngược dòng ở mức 5 phút, vì vậy, thay vào đó, Hermes sử dụng điểm dừng 5 phút TTL ở đó. Các đường dẫn Claude-thông qua bên thứ ba khác (AWS Bedrock, Azure Foundry) quay trở lại mặc định bộ nhớ đệm của nhà cung cấp. xAI Grok sử dụng cơ chế id hội thoại được ghim theo phiên riêng biệt — xem [xAI prompt caching](/docs/integrations/providers#xai-grok--responses-API--prompt-caching).

Không có núm nào để tắt tính năng này — bộ nhớ đệm luôn bật và tiết kiệm tiền ngay cả trong các cuộc trò chuyện một lượt vì chỉ riêng lời nhắc hệ thống đã là một phần có ý nghĩa trong số lượng mã thông báo đầu vào.`##Mô hình phụ trợHermes sử dụng các mô hình "phụ trợ" cho các tác vụ phụ như phân tích hình ảnh, tóm tắt trang web, phân tích ảnh chụp màn hình trình duyệt, tạo tiêu đề phiên và nén ngữ cảnh. Theo mặc định (
`auxiliary.*.provider: "auto"

), Hermes định tuyến mọi nhiệm vụ phụ trợ tới **mô hình trò chuyện chính** của bạn — cùng nhà cung cấp/mô hình mà bạn đã chọn trong 
`Hermes model

. Bạn không cần phải định cấu hình bất kỳ thứ gì để bắt đầu, nhưng hãy lưu ý rằng trên các mô hình lý luận đắt tiền (Opus, MiniMax M2.7, v.v.), các tác vụ phụ sẽ tăng thêm chi phí đáng kể. Nếu bạn muốn các tác vụ phụ rẻ và nhanh bất kể mô hình chính của bạn là gì, hãy đặt rõ ràng 
`auxiliary.<task.provider
` và 
`auxiliary.<task.model
` (ví dụ: Gemini Flash trên OpenRouter để trích xuất thị giác và web).

:::note[Why "auto" uses your main model]
Trước đó, xây dựng người dùng tổng hợp phân chia (OpenRouter, Nous Portal) theo mặc định phía nhà cung cấp giá rẻ. Điều đó thật đáng ngạc nhiên — những người dùng đã trả tiền đăng ký công cụ tổng hợp sẽ thấy một mô hình khác xử lý lưu lượng truy cập phụ của họ. 
`auto
` hiện sử dụng mô hình chính cho mọi người và ghi đè theo nhiệm vụ trong 
`config.yaml
` vẫn giành chiến thắng (xem [Full auxiliary config reference](#full-auxiliary-config-reference) bên dưới).

:::

### Cấu hình tương tác các mô hình phụ trợ

Thay vì chỉnh sửa YAML bằng tay, hãy chạy 
`Hermes model
` và chọn **"Định cấu hình các mô hình phụ trợ"** từ menu. Bạn sẽ nhận được một bộ chọn tương tác cho mỗi tác vụ:

`
$ Hermes model
→ Configure auxiliary models`[ ] vision               currently: auto / main model
[ ] web_extract          currently: auto / main model
[ ] title_generation     currently: OpenRouter / Google/Gemini-3-flash-preview
[ ] compression          currently: auto / main model
[ ] approval             currently: auto / main model
[ ] triage_specifier     currently: auto / main model
[ ] kanban_decomposer    currently: auto / main model
[ ] profile_describer    currently: auto / main model

`
``Chọn một tác vụ, chọn một nhà cung cấp (luồng OAuth mở trình duyệt; lời nhắc của nhà cung cấp khóa API), chọn một mô hình. Thay đổi vẫn tiếp tục đối với 
`auxiliary.<task.*
` trong 
`config.yaml

. Máy móc tương tự như bộ chọn mô hình chính — không cần tìm hiểu thêm cú pháp.`###Video hướng dẫn`<div style=\{\{position: 'relative', width: '100%', aspectRatio: '16 / 9', marginBottom: '1.5rem'}}>
  <iframe
    src="https://www.youtube.com/embed/NoF-YajElIM"
    title="Hermes Agent — Auxiliary Models Tutorial"
    style=\{\{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0}}
    allow="accelerometer; autoplay; CLIpboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
  /
</div

### Mẫu cấu hình phổ quát

Mọi vị trí mô hình trong Hermes — tác vụ phụ, nén, dự phòng — đều sử dụng ba nút giống nhau:

| Chìa khóa | Nó làm gì | Mặc định |
|------|-------------|----------|
| 
`provider
` | Nhà cung cấp nào sẽ sử dụng để xác thực và định tuyến |

"auto"
` |
| 
`model
` | Yêu cầu mẫu nào | mặc định của nhà cung cấp |
| 
`base_url
` | Điểm cuối tương thích OpenAI tùy chỉnh (ghi đè nhà cung cấp) | chưa được đặt |

Khi 
`base_url
` được đặt, Hermes bỏ qua nhà cung cấp và gọi trực tiếp điểm cuối đó (sử dụng 
`API_key
` hoặc 
`OpenAI_API_KEY
` để xác thực). Khi chỉ đặt 
`provider

, Hermes sử dụng URL cơ sở và xác thực tích hợp của nhà cung cấp đó.

Các nhà cung cấp có sẵn cho các nhiệm vụ phụ trợ: 
`auto

, 
`main

, cùng với bất kỳ nhà cung cấp nào trong [provider registry](/docs/reference/environment-variables) — 
`OpenRouter

, 
`nous

, 
`OpenAI-Codex

, 
`copilot

, 
`copilot-ACP

, 
`Anthropic

, 
`Gemini

, 
`Google-Gemini-CLI

, 
`qwen-OAuth

, 
`zai

, 
`Kimi-coding

, 
`Kimi-coding-cn

, 
`MiniMax

, 
`MiniMax-cn

, 
`MiniMax-OAuth

, 
`DeepSeek

, 
`nvidia

, 
`xai

, 
`xai-OAuth

, 
`OLlama-cloud

, 
`alibaba

, 
`bedrock

, 
`huggingface

, 
`arcee

, 
`xiaomi

, 
`kilocode

, 
`opencode-zen

, 
`opencode-go

, 
`ai-gateway

, 
`azure-foundry
` — hoặc bất kỳ nhà cung cấp tùy chỉnh có tên nào từ danh sách 
`custom_providers
` của bạn (ví dụ: 
`provider: "beans"

).

:::tip[MiniMax OAuth]
`MiniMax-OAuth
` đăng nhập qua trình duyệt OAuth (không cần khóa API). Chạy 
`Hermes model
` và chọn **MiniMax (OAuth)** để xác thực. Các tác vụ phụ trợ sử dụng 
`MiniMax-M2.7-highspeed
` một cách tự động. Xem [MiniMax OAuth guide](../guides/MiniMax-OAuth.md).
:::

:::tip[xAI Grok OAuth]
`xai-OAuth
` đăng nhập qua trình duyệt OAuth dành cho người đăng ký SuperGrok và X Premium+ (không cần khóa API). Chạy 
`Hermes model
` và chọn **xAI Grok OAuth (Đăng ký SuperGrok)** để xác thực. Mã thông báo OAuth tương tự được sử dụng lại cho mọi bề mặt trực tiếp tới xAI (trò chuyện, tác vụ phụ trợ, TTS, gen hình ảnh, gen video, phiên âm). Xem [xAI Grok OAuth guide](../guides/xai-grok-OAuth.md) và nếu Hermes ở trên máy chủ từ xa, hãy xem [OAuth over SSH / Remote Hosts](../guides/OAuth-over-SSH.md).
::::::warning[XPROTECTX407XPROTECTX is for auxiliary tasks only]
Tùy chọn nhà cung cấp 

"main"
` có nghĩa là "sử dụng bất kỳ nhà cung cấp nào mà tác nhân chính của tôi sử dụng" — tùy chọn này chỉ hợp lệ trong các cấu hình 
`auxiliary:

, 
`compression:
` và 
`fallback_model:

. Đó **không** là giá trị hợp lệ cho cài đặt 
`model.provider
` cấp cao nhất của bạn. Nếu bạn sử dụng điểm cuối tương thích với OpenAI tùy chỉnh, hãy đặt 
`provider: custom
` trong phần 
`model:
` của bạn. Xem [AI Providers](/docs/integrations/providers) để biết tất cả các tùy chọn nhà cung cấp mô hình chính.
:::

### Tham khảo cấu hình phụ trợ đầy đủ

``` yaml
auxiliary:

  # Image analysis (vision_analyze tool + browser screenshots)
  vision:
    provider: "auto"           # "auto", "OpenRouter", "nous", "Codex", "main", etc.
    model: ""                  # e.g. "OpenAI/GPT-4o", "Google/Gemini-2.5-flash"
    base_url: ""               # Custom OpenAI-compatible endpoint (overrides provider)
    API_key: ""                # API key for base_url (falls back to OpenAI_API_KEY)
    timeout: 120               # seconds — LLM API call timeout; vision payloads need generous timeout
    download_timeout: 30       # seconds — image HTTP download; increase for slow connections

# Web page summarization + browser page text extraction
  web_extract:
    provider: "auto"
    model: ""                  # e.g. "Google/Gemini-2.5-flash"
    base_url: ""
    API_key: ""
    timeout: 360               # seconds (6min) — per-attempt LLM summarization

# Dangerous command approval classifier
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    API_key: ""
    timeout: 30                # seconds

# Context compression timeout (separate from compression.* config)
  compression:
    timeout: 120               # seconds — compression summarizes long conversations, needs more time

# Skills hub — skill matching and search
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    API_key: ""
    timeout: 30

# MCP tool dispatch
  MCP:
    provider: "auto"
    model: ""
    base_url: ""
    API_key: ""
    timeout: 30

# Kanban triage specifier — 
`Hermes kanban specify <id
` (or the
  # dashboard's ✨ Specify button on Triage-column cards) uses this
  # slot to expand a one-liner into a concrete spec and promote the
  # task to 
`todo

. Cheap fast models work well here; spec expansion
  # is short and doesn't need reasoning depth.
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    API_key: ""
    timeout: 120

`

:::tip
Mỗi tác vụ phụ trợ có 
`timeout
` có thể định cấu hình (tính bằng giây). Mặc định: tầm nhìn 120 giây, web_extract 360 giây, phê duyệt 30 giây, nén 120 giây. Hãy tăng mức này nếu bạn sử dụng các mô hình cục bộ chậm cho các tác vụ phụ trợ. Vision cũng có 
`download_timeout
` riêng biệt (30 giây mặc định) để tải xuống hình ảnh HTTP — tăng mức này cho các kết nối chậm hoặc máy chủ hình ảnh tự lưu trữ.
:::

:::info
Nén ngữ cảnh có khối 
`compression:
` riêng cho các ngưỡng và khối 
`auxiliary.compression:
` cho cài đặt kiểu máy/nhà cung cấp - xem [Context Compression](#context-compression) ở trên. Mô hình dự phòng sử dụng khối 
`fallback_model:

 - xem [Fallback Model](/docs/integrations/providers#fallback-model). Cả ba đều tuân theo cùng một mẫu nhà cung cấp/mô hình/base_url.
:::

### Định tuyến OpenRouter & Mã Pareto cho các tác vụ phụ trợ

Khi một tác vụ phụ phân giải thành OpenRouter (rõ ràng hoặc thông qua 
`provider: "main"
` trong khi tác nhân chính của bạn ở trên OpenRouter), các cài đặt 
`provider_routing
` và 
`OpenRouter.min_coding_score
` của tác nhân chính **không truyền bá** — theo thiết kế, mỗi tác vụ phụ trợ đều độc lập. Để đặt tùy chọn của nhà cung cấp OpenRouter hoặc sử dụng [Pareto Code router](/docs/integrations/providers#OpenRouter-pareto-code-router) cho một tác vụ phụ trợ cụ thể, hãy đặt chúng cho mỗi tác vụ thông qua 
`extra_body

:

``` yaml
auxiliary:
  compression:
    provider: OpenRouter
    model: OpenRouter/pareto-code         # use the Pareto Code router for this task
    extra_body:
      provider:                            # OpenRouter provider routing prefs
        order: [Anthropic, Google]         # try these providers in order
        sort: throughput                   # or "price" | "latency"

        # only: [Anthropic]                # restrict to a specific provider
        # ignore: [deepinfra]              # exclude specific providers
      plugins:                             # OpenRouter Pareto Code router knob
        - id: pareto-router
          min_coding_score: 0.5            # 0.0–1.0; higher = stronger coders

`
``Hình dạng phản ánh những gì OpenRouter chấp nhận trong nội dung yêu cầu hoàn thành trò chuyện. Hermes chuyển tiếp toàn bộ nguyên văn 
`extra_body

, vì vậy mọi trường nội dung yêu cầu OpenRouter khác được ghi lại tại [OpenRouter.ai/docs](https://OpenRouter.ai/docs) đều hoạt động theo cách tương tự.

### Thay đổi mô hình tầm nhìn

Để sử dụng GPT-4o thay vì Gemini Flash để phân tích hình ảnh:

``` yaml
auxiliary:
  vision:
    model: "OpenAI/GPT-4o"

`
``Hoặc thông qua biến môi trường (trong 

~/.Hermes/.env

):

`bash
AUXILIARY_VISION_MODEL=OpenAI/GPT-4o

`

### Tùy chọn nhà cung cấp

Các tùy chọn này áp dụng cho **cấu hình tác vụ phụ trợ** (
`auxiliary:

, 
`compression:

, 
`fallback_model:

), không áp dụng cho cài đặt 
`model.provider
` chính của bạn.

| Nhà cung cấp | Mô tả | Yêu cầu |
|----------|-------------|-------------|
| 

"auto"
` | Tốt nhất hiện có (mặc định). Vision thử OpenRouter → Nous → Codex. | — |
| 

"OpenRouter"
` | Buộc OpenRouter - định tuyến đến bất kỳ kiểu máy nào (Gemini, GPT-4o, Claude, v.v.) |

OpenRouter_API_KEY
` |
| 

"nous"
` | Cổng thông tin buộc Nous |

Hermes auth
` |
| 

"Codex"
` | Buộc Codex OAuth (tài khoản ChatGPT). Hỗ trợ tầm nhìn (GPT-5.3-Codex). |

Hermes model
` → Codex |
| 

"MiniMax-OAuth"
` | Buộc MiniMax OAuth (đăng nhập trình duyệt, không cần khóa API). Sử dụng MiniMax-M2.7-tốc độ cao cho các tác vụ phụ trợ. |

Hermes model
` → MiniMax (OAuth) |
| 

"xai-OAuth"
` | Buộc xAI Grok OAuth (đăng nhập trình duyệt cho người đăng ký SuperGrok hoặc X Premium+, không cần khóa API). Mã thông báo OAuth tương tự bao gồm trò chuyện, TTS, hình ảnh, video và phiên âm. |

Hermes model
` → xAI Grok OAuth (Đăng ký SuperGrok) |
| 

"main"
` | Sử dụng điểm cuối tùy chỉnh/chính đang hoạt động của bạn. Điều này có thể đến từ 
`OpenAI_BASE_URL

 + 
`OpenAI_API_KEY
` hoặc từ điểm cuối tùy chỉnh được lưu qua 
`Hermes model
` / 
`config.yaml

. Hoạt động với OpenAI, mô hình cục bộ hoặc bất kỳ API tương thích với OpenAI nào. **Chỉ các tác vụ phụ trợ — không hợp lệ đối với 
`model.provider

.** | Thông tin xác thực điểm cuối tùy chỉnh + URL cơ sở |

Các nhà cung cấp khóa API trực tiếp từ danh mục nhà cung cấp chính cũng hoạt động ở đây khi bạn muốn các tác vụ phụ bỏ qua bộ định tuyến mặc định của mình. 
`gmi
` hợp lệ khi 
`GMI_API_KEY
` được định cấu hình:

`YAML
auxiliary:
  compression:
    provider: "gmi"
    model: "Anthropic/Claude-opus-4.6"

`
``Để định tuyến phụ trợ GMI, hãy sử dụng ID mẫu chính xác được điểm cuối 

/v1/models
` của GMI trả về.

### Các thiết lập phổ biến`**Sử dụng điểm cuối tùy chỉnh trực tiếp** (rõ ràng hơn 
`provider: "main"
` dành cho API cục bộ/tự lưu trữ):

`
`YAML
auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    API_key: "local-key"
    model: "qwen2.5-vl"

`

`base_url
` được ưu tiên hơn 
`provider

, vì vậy đây là cách rõ ràng nhất để định tuyến tác vụ phụ trợ đến điểm cuối cụ thể. Để ghi đè điểm cuối trực tiếp, Hermes sử dụng 
`API_key
` đã định cấu hình hoặc quay lại 
`OpenAI_API_KEY

; nó không sử dụng lại 
`OpenRouter_API_KEY
` cho điểm cuối tùy chỉnh đó.

**Sử dụng khóa API OpenAI cho tầm nhìn:**

`
`YAML

# In ~/.Hermes/.env:
# OpenAI_BASE_URL=https://API.OpenAI.com/v1
# OpenAI_API_KEY=sk-...

auxiliary:
  vision:
    provider: "main"
    model: "GPT-4o"       # or "GPT-4o-mini" for cheaper

`
``**Sử dụng OpenRouter cho tầm nhìn** (định tuyến tới bất kỳ kiểu máy nào):

`
``` yaml
auxiliary:
  vision:
    provider: "OpenRouter"
    model: "OpenAI/GPT-4o"      # or "Google/Gemini-2.5-flash", etc.

`
``**Sử dụng Codex OAuth** (tài khoản ChatGPT Pro/Plus — không cần khóa API):

`
`YAML
auxiliary:
  vision:
    provider: "Codex"     # uses your ChatGPT OAuth token

    # model defaults to GPT-5.3-Codex (supports vision)

`
``**Sử dụng MiniMax OAuth** (đăng nhập trình duyệt, không cần khóa API):

`
``` yaml
model:
  default: MiniMax-M2.7
  provider: MiniMax-OAuth
  base_url: https://API.MiniMax.io/Anthropic

`

Chạy 
`Hermes model
` và chọn **MiniMax (OAuth)** để đăng nhập và thiết lập tự động. Đối với khu vực Trung Quốc, URL cơ sở sẽ là 
`https://API.MiniMaxi.com/Anthropic

. Xem [MiniMax OAuth guide](../guides/MiniMax-OAuth.md) để biết hướng dẫn đầy đủ.

**Sử dụng mô hình cục bộ/tự lưu trữ:**

`
`YAML
auxiliary:
  vision:
    provider: "main"      # uses your active custom endpoint
    model: "my-local-model"

`
```provider: "main"
` sử dụng bất kỳ nhà cung cấp nào mà Hermes sử dụng để trò chuyện thông thường — cho dù đó là nhà cung cấp tùy chỉnh có tên (ví dụ: 
`beans

), nhà cung cấp tích hợp như 
`OpenRouter
` hay điểm cuối 
`OpenAI_BASE_URL
` cũ.

:::tip
Nếu bạn sử dụng Codex OAuth làm nhà cung cấp mô hình chính, thì tầm nhìn sẽ tự động hoạt động — không cần cấu hình bổ sung. Codex được bao gồm trong chuỗi phát hiện tự động cho tầm nhìn.

:::

:::warning
**Tầm nhìn yêu cầu mô hình đa phương thức.** Nếu bạn đặt 
`provider: "main"

, hãy đảm bảo điểm cuối của bạn hỗ trợ đa phương thức/tầm nhìn — nếu không thì quá trình phân tích hình ảnh sẽ không thành công.
:::

### Biến môi trường (cũ)

Các mô hình phụ trợ cũng có thể được cấu hình thông qua các biến môi trường. Tuy nhiên, 
`config.yaml
` là phương pháp được ưu tiên — nó dễ quản lý hơn và hỗ trợ tất cả các tùy chọn bao gồm 
`base_url
` và 
`API_key

.

| Cài đặt | Biến môi trường |
|----------|----------------------|
| Nhà cung cấp thị lực |

AUXILIARY_VISION_PROVIDER
` |
| Mô hình tầm nhìn |

AUXILIARY_VISION_MODEL
` |
| Điểm cuối tầm nhìn |

AUXILIARY_VISION_BASE_URL
` |
| Khóa API tầm nhìn |

AUXILIARY_VISION_API_KEY
` |
| Nhà cung cấp trích xuất web |

AUXILIARY_WEB_EXTRACT_PROVIDER
` |
| Mô hình trích xuất web |

AUXILIARY_WEB_EXTRACT_MODEL
` |
| Điểm cuối trích xuất web |

AUXILIARY_WEB_EXTRACT_BASE_URL
` |
| Khóa API trích xuất web |

AUXILIARY_WEB_EXTRACT_API_KEY
` |

Cài đặt mô hình nén và dự phòng chỉ có ở config.yaml.

:::tip
Chạy 
`Hermes config
` để xem cài đặt mô hình phụ trợ hiện tại của bạn. Phần ghi đè chỉ hiển thị khi chúng khác với giá trị mặc định.
:::

## Nỗ lực lý luận

Kiểm soát mức độ "suy nghĩ" của mô hình trước khi phản hồi:

``` yaml
agent:
  reasoning_effort: ""   # empty = medium (default). Options: none, minimal, low, medium, high, xhigh (max)

`
``Khi không được đặt (mặc định), nỗ lực suy luận sẽ mặc định ở mức "trung bình" — mức cân bằng phù hợp với hầu hết các nhiệm vụ. Việc đặt một giá trị sẽ ghi đè lên giá trị đó — nỗ lực suy luận cao hơn sẽ mang lại kết quả tốt hơn cho các tác vụ phức tạp với chi phí là nhiều mã thông báo và độ trễ hơn.

Bạn cũng có thể thay đổi cách suy luận trong thời gian chạy bằng lệnh 

/reasoning

:

`
/reasoning           # Show current effort level and display state
/reasoning high      # Set reasoning effort to high
/reasoning none      # Disable reasoning
/reasoning show      # Show model thinking above each response
/reasoning hide      # Hide model thinking

`

## Thực thi việc sử dụng công cụ

Một số mô hình đôi khi mô tả các hành động dự định dưới dạng văn bản thay vì thực hiện lệnh gọi công cụ ("Tôi sẽ chạy thử nghiệm..." thay vì thực sự gọi terminal). Việc thực thi sử dụng công cụ đưa vào hướng dẫn nhanh chóng của hệ thống để đưa mô hình quay trở lại các công cụ gọi thực tế.

`YAML
agent:
  tool_use_enforcement: "auto"   # "auto" | true | false | ["model-substring", ...]

`

| Giá trị | Hành vi |
|-------|----------|
| 

"auto"
` (mặc định) | Được bật cho các mẫu phù hợp: 
`GPT

, 
`Codex

, 
`Gemini

, 
`gemma

, 
`grok

. Bị vô hiệu hóa đối với tất cả những người khác (Claude, DeepSeek, Qwen, v.v.). |
| 
`true
` | Luôn được bật, bất kể kiểu máy. Hữu ích nếu bạn nhận thấy mô hình hiện tại của mình mô tả các hành động thay vì thực hiện chúng. |
| 
`false
` | Luôn bị vô hiệu hóa, bất kể kiểu máy. |
| 

["GPT", "Codex", "qwen", "Llama"]
` | Chỉ được bật khi tên mẫu chứa một trong các chuỗi con được liệt kê (không phân biệt chữ hoa chữ thường). |

### Nó tiêm cái gì

Khi được bật, ba lớp hướng dẫn có thể được thêm vào lời nhắc hệ thống:
1. **Thực thi sử dụng công cụ chung** (tất cả các mô hình phù hợp) — hướng dẫn mô hình thực hiện lệnh gọi công cụ ngay lập tức thay vì mô tả ý định, tiếp tục làm việc cho đến khi nhiệm vụ hoàn thành và không bao giờ kết thúc lượt bằng lời hứa về hành động trong tương lai.2. **Kỷ luật thực thi OpenAI** (chỉ dành cho mô hình GPT và Codex) — hướng dẫn bổ sung giải quyết các chế độ lỗi dành riêng cho GPT: bỏ qua công việc đối với kết quả một phần, bỏ qua tra cứu điều kiện tiên quyết, ảo giác thay vì sử dụng công cụ và tuyên bố "hoàn thành" mà không xác minh.
3. **Hướng dẫn vận hành của Google** (chỉ dành cho kiểu máy Gemini và Gemma) — tính ngắn gọn, đường dẫn tuyệt đối, lệnh gọi công cụ song song và mẫu xác minh trước khi chỉnh sửa.

Những điều này minh bạch đối với người dùng và chỉ ảnh hưởng đến lời nhắc hệ thống. Những mô hình đã sử dụng các công cụ một cách đáng tin cậy (như Claude) không cần hướng dẫn này, đó là lý do tại sao 

"auto"
` loại trừ chúng.

### Khi nào nên bật nó lên

Nếu bạn đang sử dụng một mô hình không có trong danh sách tự động mặc định và nhận thấy mô hình đó thường xuyên mô tả những gì nó *sẽ* làm thay vì thực hiện, hãy đặt 
`tool_use_enforcement: true
` hoặc thêm chuỗi con mô hình vào danh sách:

`YAML
agent:
  tool_use_enforcement: ["GPT", "Codex", "Gemini", "grok", "my-custom-model"]

`

## Cấu hình TTS

`YAML
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "OpenAI" | "MiniMax" | "Mistral" | "Gemini" | "xai" | "neutts"
  speed: 1.0                    # Global speed multiplier (fallback for all providers)
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
    speed: 1.0                  # Speed multiplier (converted to rate percentage, e.g. 1.5 → +50%)
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  OpenAI:
    model: "GPT-4o-mini-tts"
    voice: "alloy"              # alloy, echo, fable, onyx, nova, shimmer
    speed: 1.0                  # Speed multiplier (clamped to 0.25–4.0 by the API)
    base_url: "https://API.OpenAI.com/v1"  # Override for OpenAI-compatible TTS endpoints
  MiniMax:
    speed: 1.0                  # Speech speed multiplier

    # base_url: ""              # Optional: override for OpenAI-compatible TTS endpoints
  Mistral:
    model: "voxtral-mini-tts-2603"
    voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8"  # Paul - Neutral (default)
  Gemini:
    model: "Gemini-2.5-flash-preview-tts"   # or Gemini-2.5-pro-preview-tts
    voice: "Kore"               # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, etc.
  xai:
    voice_id: "eve"             # xAI TTS voice
    language: "en"              # ISO 639-1
    sample_rate: 24000
    bit_rate: 128000            # MP3 bitrate
    # base_url: "https://API.x.ai/v1"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

`
``Điều này kiểm soát cả công cụ 
`text_to_speech
` và câu trả lời bằng giọng nói ở chế độ giọng nói (

/voice tts
` trong CLI hoặc cổng nhắn tin).

**Phân cấp dự phòng tốc độ:** tốc độ dành riêng cho nhà cung cấp (ví dụ: 
`tts.edge.speed

) → 
`tts.speed
` toàn cầu → 
`1.0
` mặc định. Đặt 
`tts.speed
` toàn cầu để áp dụng tốc độ thống nhất trên tất cả các nhà cung cấp hoặc ghi đè từng nhà cung cấp để kiểm soát chi tiết hơn.

## Cài đặt hiển thị

``` yaml
display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # Enable /verbose slash command in messaging gateway
  platforms: \{}           # Per-platform display overrides (see below)
  tool_progress_overrides: \{}  # DEPRECATED — use display.platforms instead
  interim_assistant_messages: true  # Gateway: send natural mid-turn assistant updates as separate messages
  skin: default           # Built-in or custom CLI skin (see user-guide/features/skins)
  personality: "kawaii"  # Legacy cosmetic field still surfaced in some summaries
  compact: false          # Compact output mode (less whitespace)
  resume_display: full    # full (show previous messages on resume) | minimal (one-liner only)
  bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks)
  show_reasoning: false   # Show model reasoning/thinking above each response (toggle with /reasoning show|hide)
  streaming: false        # Stream tokens to terminal as they arrive (real-time output)
  show_cost: false        # Show estimated $ cost in the CLI status bar
  timestamps: false       # When true, prefixes user and assistant labels with [HH:MM] timestamps in the CLI / TUI transcript
  tool_preview_length: 0  # Max chars for tool call previews (0 = no limit, show full paths/commands)
  runtime_footer:         # Gateway: append a runtime-context footer to final replies
    enabled: false
    fields: ["model", "context_pct", "cwd"]
  file_mutation_verifier: true    # Append an advisory footer when write_file/patch calls failed this turn
  language: en            # UI language for static messages (approval prompts, some gateway replies). en | zh | zh-hant | ja | de | es | fr | tr | uk | af | ko | it | ga | pt | ru | hu

`

### Trình xác minh đột biến tệp

Khi 
`display.file_mutation_verifier
` là 
`true
` (mặc định), Hermes sẽ thêm lời khuyên một dòng vào phản hồi cuối cùng của trợ lý bất cứ khi nào lệnh gọi 
`write_file
` hoặc 
`patch
` không thành công trong lượt và không bao giờ được thay thế bằng lệnh ghi thành công vào cùng một đường dẫn. Điều này nắm bắt được loại yêu cầu quá mức "lô bản vá song song, thất bại một nửa, mô hình tóm tắt thành công" mà không yêu cầu bạn chạy 
`git status
` theo cách thủ công sau mỗi lần chỉnh sửa.

Chân trang ví dụ:

`
⚠️ File-mutation verifier: 3 file(s) were NOT modified this turn despite any wording above that may suggest otherwise. Run 
`git status
` or 
`read_file
` to confirm.
  • concepts/automatic-organization.md — [patch] Could not find match for old_string
  • concepts/lora.md — [patch] Could not find match for old_string
  • concepts/rag-pipeline.md — [patch] Could not find match for old_string

`
``Đặt 
`file_mutation_verifier: false
` (hoặc 
`Hermes_FILE_MUTATION_VERIFIER=0

) để chặn chân trang. Trình xác minh chỉ kích hoạt khi lỗi thực sự xảy ra ở cuối lượt - mô hình thử lại bản vá lỗi và thành công trong cùng một lượt sẽ không kích hoạt bản vá cho tệp đó.

### Ngôn ngữ giao diện người dùng cho tin nhắn tĩnh

Cài đặt 
`display.language
` dịch một tập hợp nhỏ các thông báo tĩnh hướng tới người dùng — lời nhắc phê duyệt CLI, một số câu trả lời lệnh gạch chéo cổng (ví dụ: thông báo khởi động lại, "hết hạn phê duyệt", "đã xóa mục tiêu"). Nó **không** dịch các phản hồi của tác nhân, dòng nhật ký, đầu ra công cụ, truy nguyên lỗi hoặc mô tả lệnh gạch chéo — những nội dung này vẫn bằng tiếng Anh. Nếu bạn muốn chính nhân viên trả lời bằng ngôn ngữ khác, chỉ cần nói với nhân viên đó trong lời nhắc hoặc tin nhắn hệ thống của bạn.

Các giá trị được hỗ trợ: 
`en
` (mặc định), 
`zh
` (Tiếng Trung giản thể), 
`ja
` (tiếng Nhật), 
`de
` (tiếng Đức), 
`es
` (tiếng Tây Ban Nha), 
`fr
` (tiếng Pháp), 
`tr
` (tiếng Thổ Nhĩ Kỳ), 
`uk
` (tiếng Ukraina). Các giá trị không xác định sẽ chuyển về tiếng Anh.

Bạn cũng có thể đặt điều này cho mỗi phiên bằng biến env 
`Hermes_LANGUAGE

, ghi đè giá trị cấu hình.

`YAML
display:
  language: zh   # CLI approval prompts appear in Chinese

`

| Chế độ | Bạn thấy gì |
|------|-------------|
| 
`off
` | Im lặng — chỉ là phản hồi cuối cùng |
| 
`new
` | Chỉ báo dao khi dao thay đổi |
| 
`all
` | Mọi cuộc gọi công cụ đều có bản xem trước ngắn (mặc định) |
| 
`verbose
` | Nhật ký gỡ lỗi, kết quả và đối số đầy đủ |

Trong CLI, chuyển qua các chế độ này với 

/verbose

. Để sử dụng 

/verbose
` trong các nền tảng nhắn tin (Telegram, Discord, Slack, v.v.), hãy đặt 
`tool_progress_command: true
` trong phần 
`display
` ở trên. Lệnh sau đó sẽ quay vòng chế độ và lưu vào config.

### Chân trang siêu dữ liệu thời gian chạy (chỉ cổng)

Khi 
`display.runtime_footer.enabled: true

, Hermes gắn một chân trang nhỏ vào bối cảnh thời gian chạy vào thông báo **cuối cùng** của mỗi lượt cổng — thông tin tương tự mà CLI hiển thị trên thanh trạng thái của nó (kiểu máy, % ngữ cảnh, cwd, thời lượng phiên, mã thông báo, chi phí). Tắt theo mặc định; chọn tham gia trên mỗi cổng nếu nhóm của bạn muốn mọi câu trả lời đều bao gồm xuất xứ.

`YAML
display:
  runtime_footer:
    enabled: true
    fields: ["model", "context_pct", "cwd"]   # any of: model, context_pct, cwd, duration, tokens, cost

`
``Lệnh gạch chéo 

/footer
` sẽ bật tắt điều này khi chạy trong bất kỳ phiên nào.

Chân trang mẫu được thêm vào câu trả lời Telegram/Discord/Slack:

`
— Claude-opus-4.7 · 12 tool calls · 2m 14s · $0.042

`
``Chỉ thông báo **cuối cùng** của lượt mới có chân trang; cập nhật tạm thời luôn sạch sẽ.

### Ghi đè tiến trình trên mỗi nền tảngCác nền tảng khác nhau có nhu cầu chi tiết khác nhau. Ví dụ: Signal không thể chỉnh sửa tin nhắn nên mỗi lần cập nhật tiến trình sẽ trở thành một tin nhắn riêng — nhiễu. Sử dụng 
`display.platforms
` để đặt chế độ trên mỗi nền tảng:

`YAML
display:
  tool_progress: all          # global default
  platforms:
    Signal:
      tool_progress: 'off'    # silence progress on Signal
    Telegram:
      tool_progress: verbose  # detailed progress on Telegram
    Slack:
      tool_progress: 'off'    # quiet in shared Slack workspace

`
``Các nền tảng không có ghi đè sẽ quay trở lại giá trị 
`tool_progress
` toàn cầu. Khóa nền tảng hợp lệ: 
`Telegram

, 
`Discord

, 
`Slack

, 
`Signal

, 
`WhatsApp

, 
`Matrix

, 
`Mattermost

, 
`email

, 
`sms

, 
`homeassistant

, 
`DingTalk

, 
`Feishu

, 
`WeCom

, 
`weixin

, 
`BlueBubbles

, 
`qqbot

. Khóa 
`display.tool_progress_overrides
` cũ vẫn tải để tương thích ngược nhưng không được dùng nữa và được di chuyển sang 
`display.platforms
` trong lần tải đầu tiên.

interim_assistant_messages
` chỉ dành cho cổng. Khi được bật, Hermes sẽ gửi các bản cập nhật trợ lý đã hoàn thành giữa lượt dưới dạng tin nhắn trò chuyện riêng biệt. Điều này độc lập với 
`tool_progress
` và không yêu cầu truyền phát qua cổng.

## Quyền riêng tư

`YAML
privacy:
  redact_pii: false  # Strip PII from LLM context (gateway only)

`
``Khi 
`redact_pii
` là 
`true

, cổng sẽ loại bỏ thông tin nhận dạng cá nhân từ lời nhắc hệ thống trước khi gửi thông tin đó tới LLM trên các nền tảng được hỗ trợ:

| Lĩnh vực | Điều trị |
|-------|----------|
| Số điện thoại (ID người dùng trên WhatsApp/Signal) | Đã băm thành 
`user_<12-char-sha256>
` |
| ID người dùng | Đã băm thành 
`user_<12-char-sha256>
` |
| ID trò chuyện | Phần số được băm, tiền tố nền tảng được giữ nguyên (
`Telegram:<hash

) |
| ID kênh trang chủ | Phần số được băm |
| Tên người dùng / tên người dùng | **Không bị ảnh hưởng** (do người dùng chọn, hiển thị công khai) |

**Hỗ trợ nền tảng:** Redaction áp dụng cho WhatsApp, Signal và Telegram. Discord và Slack bị loại trừ vì hệ thống đề cập của họ (

<@user_id>

) yêu cầu ID thực trong ngữ cảnh LLM.

Giá trị băm có tính xác định — cùng một người dùng luôn ánh xạ tới cùng một giá trị băm, do đó mô hình vẫn có thể phân biệt giữa những người dùng trong cuộc trò chuyện nhóm. Định tuyến và phân phối sử dụng các giá trị ban đầu trong nội bộ.

## Chuyển lời nói thành văn bản (STT)

`YAML
stt:
  provider: "local"            # "local" | "groq" | "OpenAI" | "Mistral"
  local:
    model: "base"              # tiny, base, small, medium, large-v3
  OpenAI:
    model: "whisper-1"         # whisper-1 | GPT-4o-mini-transcribe | GPT-4o-transcribe

  # model: "whisper-1"         # Legacy fallback key still respected

`
``Hành vi của nhà cung cấp:
- 
`local
` sử dụng 
`faster-whisper
` chạy trên máy của bạn. Cài đặt riêng với 
`pip install faster-whisper

.
- 
`groq
` sử dụng điểm cuối tương thích Whisper của Groq và đọc 
`GROQ_API_KEY

.
- 
`OpenAI
` sử dụng API giọng nói OpenAI và đọc 
`VOICE_TOOLS_OpenAI_KEY

.

Nếu nhà cung cấp được yêu cầu không có sẵn, Hermes sẽ tự động quay lại theo thứ tự sau: 
`local
` → 
`groq
` → 
`OpenAI

.

Phần ghi đè mô hình Groq và OpenAI được điều khiển theo môi trường:

``` bash
STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OpenAI_MODEL=whisper-1
GROQ_BASE_URL=https://API.groq.com/OpenAI/v1
STT_OpenAI_BASE_URL=https://API.OpenAI.com/v1

`

## Chế độ giọng nói (CLI)

`YAML
voice:
  record_key: "ctrl+b"         # Push-to-talk key inside the CLI
  max_recording_seconds: 120    # Hard stop for long recordings
  auto_tts: false               # Enable spoken replies automatically when /voice on
  beep_enabled: true            # Play record start/stop beeps in CLI voice mode
  silence_threshold: 200        # RMS threshold for speech detection
  silence_duration: 3.0         # Seconds of silence before auto-stop

`
``Sử dụng 

/voice on
` trong CLI để bật chế độ micrô, 
`record_key
` để bắt đầu/dừng ghi và 

/voice tts
` để chuyển đổi các câu trả lời bằng giọng nói. Xem [Voice Mode](/docs/user-guide/features/voice-mode) để biết cách thiết lập toàn diện và hành vi dành riêng cho nền tảng.

## Đang phát trực tuyến

Truyền mã thông báo đến terminal hoặc nền tảng nhắn tin khi chúng đến, thay vì chờ phản hồi đầy đủ.

### Truyền phát CLI

`YAML
display:
  streaming: true         # Stream tokens to terminal in real-time
  show_reasoning: true    # Also stream reasoning/thinking tokens (optional)

`
``Khi được bật, các phản hồi sẽ xuất hiện theo từng mã thông báo bên trong hộp phát trực tuyến. Các cuộc gọi công cụ vẫn được ghi lại một cách âm thầm. Nếu nhà cung cấp không hỗ trợ phát trực tuyến, nó sẽ tự động quay lại màn hình bình thường.

### Truyền phát qua cổng (Telegram, Discord, Slack)

`YAML
streaming:
  enabled: true           # Enable progressive message editing
  transport: edit         # "edit" (progressive message editing) or "off"
  edit_interval: 0.3      # Seconds between message edits
  buffer_threshold: 40    # Characters before forcing an edit flush
  Cursor: " ▉"            # Cursor shown during streaming
  fresh_final_after_seconds: 60   # Send fresh final (Telegram) when preview is this old; 0 = always edit in place

`
``Khi được bật, bot sẽ gửi tin nhắn trên mã thông báo đầu tiên, sau đó chỉnh sửa dần dần khi có nhiều mã thông báo hơn. Các nền tảng không hỗ trợ chỉnh sửa tin nhắn (Tín hiệu, Email, Trợ lý gia đình) được tự động phát hiện trong lần thử đầu tiên — tính năng phát trực tuyến bị vô hiệu hóa một cách nhẹ nhàng cho phiên đó mà không có tin nhắn tràn ngập.

Để có các bản cập nhật trợ lý giữa lượt tự nhiên riêng biệt mà không cần chỉnh sửa mã thông báo lũy tiến, hãy đặt 
`display.interim_assistant_messages: true

.

**Xử lý tràn:** Nếu văn bản truyền trực tuyến vượt quá giới hạn độ dài tin nhắn của nền tảng (~4096 ký tự), tin nhắn hiện tại sẽ được hoàn tất và tin nhắn mới sẽ tự động bắt đầu.**Bản cuối cùng mới (Telegram):** 
`editMessageText
` của Telegram giữ nguyên dấu thời gian của tin nhắn gốc, do đó, một câu trả lời phát trực tiếp trong thời gian dài sẽ giữ dấu thời gian của mã thông báo đầu tiên ngay cả sau khi hoàn thành. Khi 
`fresh_final_after_seconds > 0
` (mặc định 
`60

), câu trả lời hoàn chỉnh sẽ được gửi dưới dạng một tin nhắn hoàn toàn mới (đã xóa bản xem trước cũ đã nỗ lực hết sức) để dấu thời gian hiển thị của Telegram phản ánh thời gian hoàn thành. Các bản xem trước ngắn vẫn được hoàn thiện tại chỗ. Đặt thành 
`0
` để luôn chỉnh sửa tại chỗ.

:::note
Truyền phát bị tắt theo mặc định. Kích hoạt nó trong 

~/.Hermes/config.yaml
` để thử UX phát trực tuyến.

:::

## Cách ly phiên trò chuyện nhóm

Kiểm soát xem các cuộc trò chuyện được chia sẻ có giữ một cuộc trò chuyện cho mỗi phòng hay một cuộc trò chuyện cho mỗi người tham gia hay không:

``` yaml
group_sessions_per_user: true  # true = per-user isolation in groups/channels, false = one shared session per chat

`

- 
`true
` là cài đặt mặc định và được khuyến nghị. Trong các kênh Discord, nhóm Telegram, kênh Slack và các bối cảnh được chia sẻ tương tự, mỗi người gửi sẽ có phiên riêng khi nền tảng cung cấp ID người dùng.

- 
`false
` quay lại trạng thái phòng chung cũ. Điều đó có thể hữu ích nếu bạn rõ ràng muốn Hermes coi kênh giống như một cuộc trò chuyện cộng tác, nhưng điều đó cũng có nghĩa là người dùng chia sẻ bối cảnh, chi phí mã thông báo và trạng thái gián đoạn.
- Tin nhắn trực tiếp không bị ảnh hưởng. Hermes vẫn khóa DM bằng chat/DM ID như thường lệ.
- Các chủ đề vẫn bị cô lập khỏi kênh chính của chúng; với 
`true

, mỗi người tham gia cũng có phiên riêng của họ bên trong chuỗi.

Để biết chi tiết và ví dụ về hành vi, hãy xem [Sessions](/docs/user-guide/sessions) và [Discord guide](/docs/user-guide/messaging/Discord).

## Hành vi DM trái phép

Kiểm soát những gì Hermes làm khi một người dùng không xác định gửi tin nhắn trực tiếp:

``` yaml
unauthoriZed_dm_behavior: pair

WhatsApp:
  unauthoriZed_dm_behavior: ignore

`

- 
`pair
` là mặc định. Hermes từ chối quyền truy cập nhưng trả lời bằng mã ghép nối một lần trong DM.

- 
`ignore
` âm thầm loại bỏ các DM trái phép.
- Các phần nền tảng ghi đè mặc định chung, do đó bạn có thể tiếp tục kích hoạt ghép nối rộng rãi trong khi làm cho một nền tảng yên tĩnh hơn.

## Lệnh nhanh

Xác định các lệnh tùy chỉnh chạy các lệnh shell mà không gọi LLM hoặc đặt bí danh cho một lệnh gạch chéo này cho một lệnh khác. Các lệnh nhanh của Exec không có mã thông báo và hữu ích từ các nền tảng nhắn tin (Telegram, Discord, v.v.) để kiểm tra nhanh máy chủ hoặc các tập lệnh tiện ích.

``` yaml
quick_commands:
  status:
    type: exec
    command: systemctl status Hermes-agent
  disk:
    type: exec
    command: df -h /
  update:
    type: exec
    command: cd ~/.Hermes/Hermes-agent && git pull && pip install -e .
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader
  restart:
    type: alias
    target: /gateway restart

`
``Cách sử dụng: nhập 

/status

, 

/disk

, 

/update

, 

/gpu
` hoặc 

/restart
` trong CLI hoặc bất kỳ nền tảng nhắn tin nào. Các lệnh 
`exec
` chạy cục bộ trên máy chủ và trả về kết quả đầu ra trực tiếp — không có lệnh gọi LLM, không tiêu thụ mã thông báo. Các lệnh 
`alias
` được ghi lại vào mục tiêu lệnh gạch chéo đã được định cấu hình.
- **Thời gian chờ 30 giây** — các lệnh chạy dài bị tắt kèm theo thông báo lỗi

- **Ưu tiên** — lệnh nhanh được kiểm tra trước lệnh kỹ năng, vì vậy bạn có thể ghi đè tên kỹ năng
- **Tự động hoàn thành** — các lệnh nhanh được giải quyết tại thời điểm gửi đi và không được hiển thị trong các bảng tự động hoàn thành lệnh gạch chéo tích hợp
- **Loại** — các loại được hỗ trợ là 
`exec
` và 
`alias

; các loại khác hiển thị lỗi
- **Hoạt động ở mọi nơi** — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant

Các phím tắt nhắc nhở chỉ có chuỗi không phải là lệnh nhanh hợp lệ. Đối với quy trình làm việc nhắc nhở có thể sử dụng lại, hãy tạo một kỹ năng hoặc bí danh cho lệnh gạch chéo hiện có.

## Sự chậm trễ của con người

Mô phỏng nhịp độ phản hồi giống con người trong nền tảng nhắn tin:

``` yaml
human_delay:
  mode: "off"                  # off | natural | custom
  min_ms: 800                  # Minimum delay (custom mode)
  max_ms: 2500                 # Maximum delay (custom mode)

`

## Thực thi mã

Định cấu hình công cụ 
`execute_code

:

`YAML
code_execution:
  mode: project                # project (default) | strict
  timeout: 300                 # Max execution time in seconds
  max_tool_calls: 50           # Max tool calls within code execution

`
``**
`mode

`
** kiểm soát thư mục làm việc và trình thông dịch Python cho các tập lệnh:
- **
`project

** (mặc định) — các tập lệnh chạy trong thư mục làm việc của phiên với Python của virtualenv/conda env đang hoạt động. Các dự án (
`pandas

, 
`torch

, gói dự án) và các đường dẫn tương đối (

.env

, 

./data.csv

) giải quyết một cách tự nhiên, khớp với những gì 
`terminal()
` thấy.
- **
`strict

** — các tập lệnh chạy trong thư mục dàn dựng tạm thời với 
`sys.executable
` (con trăn của riêng Hermes). Khả năng tái tạo tối đa, nhưng các dự án và đường dẫn tương đối sẽ không giải quyết được.

Lọc môi trường (dải 

*_API_KEY

, 

*_TOKEN

, 

*_SECRET

, 

*_PASSWORD

, 

*_CREDENTIAL

, 

*_PASSWD

, 

*_AUTH

) và danh sách trắng công cụ áp dụng giống hệt nhau ở cả hai chế độ — chế độ chuyển đổi không thay đổi trạng thái bảo mật.

## Phần cuối của Tìm kiếm trên WebCác công cụ 
`web_search

, 
`web_extract
` và 
`web_crawl
` hỗ trợ năm nhà cung cấp phụ trợ. Định cấu hình phần phụ trợ trong 
`config.yaml
` hoặc thông qua 
`Hermes tools

:

``` yaml
web:
  backend: firecrawl    # firecrawl | searxng | parallel | tavily | exa

# Or use per-capability keys to mix providers (e.g. free search + paid extract):
  search_backend: "searxng"
  extract_backend: "firecrawl"

`

| Phần cuối | Env Var | Tìm kiếm | Trích xuất | Thu thập thông tin |
|--------------|----------|--------|--------------|-------|
| **Bắn pháo** (mặc định) |

FIRECRAWL_API_KEY
` | ✔ | ✔ | ✔ |
| **SearXNG** |

SEARXNG_URL
` | ✔ | — | — |
| **Song song** |

PARALLEL_API_KEY
` | ✔ | ✔ | — |
| **Tavily** |

TAVILY_API_KEY
` | ✔ | ✔ | ✔ |
| **Exa** |

EXA_API_KEY
` | ✔ | ✔ | — |

**Lựa chọn phần phụ trợ:** Nếu 
`web.backend
` không được đặt, phần phụ trợ sẽ tự động được phát hiện từ các khóa API có sẵn. Nếu chỉ đặt 
`SEARXNG_URL

, SearXNG sẽ được sử dụng. Nếu chỉ đặt 
`EXA_API_KEY

, Exa sẽ được sử dụng. Nếu chỉ đặt 
`TAVILY_API_KEY
` thì Tavily sẽ được sử dụng. Nếu chỉ đặt 
`PARALLEL_API_KEY

, Parallel sẽ được sử dụng. Nếu không thì Firecrawl là mặc định.

**SearXNG** là công cụ tìm kiếm siêu dữ liệu miễn phí, tự lưu trữ, tôn trọng quyền riêng tư, truy vấn hơn 70 công cụ tìm kiếm. Không cần khóa API — chỉ cần đặt 
`SEARXNG_URL
` cho phiên bản của bạn (ví dụ: 
`http://localhost:8080

). SearXNG chỉ dành cho tìm kiếm; 
`web_extract
` và 
`web_crawl
` yêu cầu nhà cung cấp giải nén riêng (đặt 
`web.extract_backend

). Xem [Web Search setup guide](/docs/user-guide/features/web-search) để biết hướng dẫn thiết lập Docker.

**Firecrawl tự lưu trữ:** Đặt 
`FIRECRAWL_API_URL
` để trỏ đến phiên bản của riêng bạn. Khi một URL tùy chỉnh được đặt, khóa API sẽ trở thành tùy chọn (đặt 
`USE_DB_AUTHENTICATION=*** trên máy chủ để tắt xác thực).

**Chế độ tìm kiếm song song:** Đặt 
`PARALLEL_SEARCH_MODE
` để kiểm soát hành vi tìm kiếm — 
`fast

, 
`one-shot
` hoặc 
`agentic
` (mặc định: 
`agentic

).

**Exa:** Đặt 
`EXA_API_KEY
` trong 

~/.Hermes/.env

. Hỗ trợ lọc 
`category
` (
`company

, 
`research paper

, 
`news

, 
`people

, 
`personal site

, 
`pdf

) và bộ lọc tên miền/ngày.

## Trình duyệt

Định cấu hình hành vi tự động hóa trình duyệt:

`YAML
browser:
  inactivity_timeout: 120        # Seconds before auto-closing idle sessions
  command_timeout: 30             # Timeout in seconds for browser commands (screenshot, navigate, etc.)
  record_sessions: false         # Auto-record browser sessions as WebM videos to ~/.Hermes/browser_recordings/

  # Optional CDP override — when set, Hermes attaches directly to your own
  # Chromium-family browser (via /browser connect) rather than starting a headless browser.
  cdp_url: ""
  # Dialog supervisor — controls how native JS dialogs (alert / confirm / prompt)
  # are handled when a CDP backend is attached (Browserbase, local Chromium-family
  # browser via /browser connect). Ignored on Camofox and default local agent-browser mode.
  dialog_policy: must_respond    # must_respond | auto_dismiss | auto_accept
  dialog_timeout_s: 300          # Safety auto-dismiss under must_respond (seconds)
  camofox:
    managed_persistence: false   # When true, Camofox sessions persist cookies/logins across restarts
    user_id: ""                  # Optional externally managed Camofox userId
    session_key: ""              # Optional session key sent when Hermes creates a tab
    adopt_existing_tab: false    # Reuse an existing tab for this identity before creating one

`
``**Chính sách hộp thoại:**
- 
`must_respond
` (mặc định) — chụp hộp thoại, hiển thị hộp thoại trong 
`browser_snapshot.pending_dialogs
` và đợi nhân viên gọi 
`browser_dialog(action=...)

. Sau 
`dialog_timeout_s
` giây mà không có phản hồi, hộp thoại sẽ tự động bị loại bỏ để ngăn luồng JS của trang bị đình trệ vĩnh viễn.
- 
`auto_dismiss
` — bắt giữ, loại bỏ ngay lập tức. Sau khi thực tế, nhân viên vẫn nhìn thấy bản ghi hộp thoại trong 
`browser_snapshot.recent_dialogs
` với 
`closed_by="auto_policy"

.
- 
`auto_accept
` — chụp, nhận ngay. Hữu ích cho các trang có lời nhắc 
`beforeunload
` linh hoạt.

Xem [browser feature page](./features/browser.md#browser_dialog) để biết toàn bộ quy trình làm việc của hộp thoại.

Bộ công cụ trình duyệt hỗ trợ nhiều nhà cung cấp. Xem [Browser feature page](/docs/user-guide/features/browser) để biết chi tiết về Cơ sở trình duyệt, Sử dụng trình duyệt và thiết lập CDP dòng Chrome cục bộ.

## Múi giờ

Ghi đè múi giờ cục bộ của máy chủ bằng chuỗi múi giờ IANA. Ảnh hưởng đến dấu thời gian trong nhật ký, lập lịch cron và chèn thời gian nhắc nhở hệ thống.

``` yaml
timezone: "America/New_York"   # IANA timezone (default: "" = server-local time)

`
``Các giá trị được hỗ trợ: bất kỳ mã định danh múi giờ IANA nào (ví dụ: 
`America/New_York

, 
`Europe/London

, 
`Asia/Kolkata

, 
`UTC

). Để trống hoặc bỏ qua giờ địa phương của máy chủ.

## Discord

Định cấu hình hành vi dành riêng cho Discord cho cổng nhắn tin:

`YAML
Discord:
  require_mention: true          # Require @mention to respond in server channels
  free_response_channels: ""     # Comma-separated channel IDs where bot responds without @mention
  auto_thread: true              # Auto-create threads on @mention in channels

`

- 
`require_mention
` — khi 
`true
` (mặc định), bot chỉ phản hồi trong các kênh máy chủ khi được đề cập với 

@BotName

. DM luôn hoạt động mà không cần đề cập đến.

- 
`free_response_channels
` — danh sách ID kênh được phân tách bằng dấu phẩy trong đó bot phản hồi mọi tin nhắn mà không yêu cầu đề cập.
- 
`auto_thread
` — khi 
`true
` (mặc định), đề cập trong các kênh sẽ tự động tạo chuỗi cho cuộc trò chuyện, giữ cho các kênh luôn sạch sẽ (tương tự như luồng Slack).

## Bảo mật

Quét bảo mật trước khi thực hiện và biên tập bí mật:

``` yaml
security:
  redact_secrets: false          # Redact API key patterns in tool output and logs (off by default)
  tirith_enabled: true           # Enable Tirith security scanning for terminal commands
  tirith_path: "tirith"          # Path to tirith binary (default: "tirith" in $PATH)
  tirith_timeout: 5              # Seconds to wait for tirith scan before timing out
  tirith_fail_open: true         # Allow command execution if tirith is unavailable
  website_blocklist:             # See Website Blocklist section below
    enabled: false
    domains: []
    shared_files: []

`

- 
`redact_secrets
` — khi 
`true

, tự động phát hiện và loại bỏ các mẫu trông giống như khóa API, mã thông báo và mật khẩu trong đầu ra của công cụ trước khi đi vào ngữ cảnh hội thoại và nhật ký. **Tắt theo mặc định** — bật nếu bạn thường làm việc với thông tin xác thực thực ở đầu ra công cụ và muốn có mạng lưới an toàn. Đặt rõ ràng thành 
`true
` để bật.

- 
`tirith_enabled
` — khi 
`true

, các lệnh đầu cuối được [Tirith](https://GitHub.com/sheeki03/tirith) quét trước khi thực thi để phát hiện các hoạt động nguy hiểm tiềm tàng.
- 
`tirith_path
` — đường dẫn đến nhị phân thứ ba. Đặt cái này nếu tirith được cài đặt ở một vị trí không chuẩn.
- 
`tirith_timeout

 - số giây tối đa để chờ quét lần thứ ba. Các lệnh tiếp tục nếu quá trình quét hết thời gian.
- 
`tirith_fail_open
` — khi 
`true
` (mặc định), các lệnh được phép thực thi nếu tirith không khả dụng hoặc bị lỗi. Đặt thành 
`false
` để chặn các lệnh khi tirith không thể xác minh chúng.

## Danh sách chặn trang web

Chặn các miền cụ thể khỏi bị truy cập bởi các công cụ trình duyệt và web của đại lý:

``` yaml
security:
  website_blocklist:
    enabled: false               # Enable URL blocking (default: false)
    domains:                     # List of blocked domain patterns

      - "*.internal.company.com"
      - "admin.example.com"
      - "*.local"
    shared_files:                # Load additional rules from external files
      - "/etc/Hermes/blocked-sites.txt"

`
``Khi được bật, mọi URL khớp với mẫu miền bị chặn sẽ bị từ chối trước khi công cụ web hoặc trình duyệt thực thi. Điều này áp dụng cho 
`web_search

, 
`web_extract

, 
`browser_navigate
` và bất kỳ công cụ nào truy cập URL.

Hỗ trợ quy tắc tên miền:
- Tên miền chính xác: 
`admin.example.com

- Tên miền phụ ký tự đại diện: 

*.internal.company.com
` (chặn tất cả tên miền phụ)
- Ký tự đại diện TLD: 

*.local
``Các tệp được chia sẻ chứa một quy tắc tên miền trên mỗi dòng (các dòng trống và nhận xét 

#
` bị bỏ qua). Các tệp bị thiếu hoặc không thể đọc được sẽ ghi lại cảnh báo nhưng không tắt các công cụ web khác.

Chính sách này được lưu vào bộ nhớ đệm trong 30 giây nên các thay đổi về cấu hình sẽ có hiệu lực nhanh chóng mà không cần khởi động lại.

## Phê duyệt thông minh

Kiểm soát cách Hermes xử lý các lệnh nguy hiểm tiềm ẩn:

``` yaml
approvals:
  mode: manual   # manual | smart | off

`

| Chế độ | Hành vi |
|------|----------|
| 
`manual
` (mặc định) | Nhắc người dùng trước khi thực hiện bất kỳ lệnh được gắn cờ nào. Trong CLI, hiển thị hộp thoại phê duyệt tương tác. Trong tin nhắn, xếp hàng yêu cầu phê duyệt đang chờ xử lý. |
| 
`smart
` | Sử dụng LLM phụ trợ để đánh giá xem lệnh được gắn cờ có thực sự nguy hiểm hay không. Các lệnh có rủi ro thấp được tự động phê duyệt với tính duy trì ở cấp phiên. Các lệnh thực sự nguy hiểm sẽ được chuyển đến người dùng. |
| 
`off
` | Bỏ qua tất cả các bước kiểm tra phê duyệt. Tương đương với 
`Hermes_YOLO_MODE=true

. **Sử dụng thận trọng.** |

Chế độ thông minh đặc biệt hữu ích để giảm bớt sự mệt mỏi khi phê duyệt — nó cho phép tác nhân làm việc tự chủ hơn trong các hoạt động an toàn trong khi vẫn bắt được các lệnh thực sự có tính phá hoại.

:::warning
Cài đặt 
`approvals.mode: off
` sẽ vô hiệu hóa tất cả các kiểm tra an toàn cho các lệnh đầu cuối. Chỉ sử dụng tính năng này trong môi trường có hộp cát, đáng tin cậy.

:::

## Điểm kiểm tra

Tự động chụp nhanh hệ thống tập tin trước khi thực hiện các thao tác phá hoại tập tin. Xem [Checkpoints & Rollback](/docs/user-guide/checkpoints-and-rollback) để biết chi tiết.

``` yaml
checkpoints:
  enabled: false                 # Enable automatic checkpoints (also: Hermes chat --checkpoints). Default: false (opt-in).
  max_snapshots: 20              # Max checkpoints to keep per directory (default: 20)

`

`

## Phái đoàn

Định cấu hình hành vi của tác nhân phụ cho công cụ ủy quyền:

``` yaml
delegation:

  # model: "Google/Gemini-3-flash-preview"  # Override model (empty = inherit parent)
  # provider: "OpenRouter"                  # Override provider (empty = inherit parent)
  # base_url: "http://localhost:1234/v1"    # Direct OpenAI-compatible endpoint (takes precedence over provider)
  # API_key: "local-key"                    # API key for base_url (falls back to OpenAI_API_KEY)
  # API_mode: ""                            # Wire protocol for base_url: "chat_completions", "Codex_responses", or "Anthropic_messages". Empty = auto-detect from URL (e.g. /Anthropic suffix → Anthropic_messages). Set explicitly for non-standard endpoints the heuristic can't detect.
  max_concurrent_children: 3                # Parallel children per batch (floor 1, no ceiling). Also via DELEGATION_MAX_CONCURRENT_CHILDREN env var.
  max_spawn_depth: 1                        # Delegation tree depth cap (1-3, clamped). 1 = flat (default): parent spawns leaves that cannot delegate. 2 = orchestrator children can spawn leaf grandchildren. 3 = three levels.
  orchestrator_enabled: true                # Global kill switch. When false, role="orchestrator" is ignored and every child is forced to leaf regardless of max_spawn_depth.

`
``**Nhà cung cấp đại lý phụ:ghi đè mô hình:** Theo mặc định, các đại lý phụ kế thừa nhà cung cấp và mô hình của đại lý chính. Đặt 
`delegation.provider
` và 
`delegation.model
` để định tuyến các tác nhân phụ đến một cặp nhà cung cấp:mô hình khác - ví dụ: sử dụng mô hình rẻ/nhanh cho các nhiệm vụ phụ có phạm vi hẹp trong khi tác nhân chính của bạn chạy mô hình lý luận đắt tiền.

**Ghi đè điểm cuối trực tiếp:** Nếu bạn muốn đường dẫn điểm cuối tùy chỉnh rõ ràng, hãy đặt 
`delegation.base_url

, 
`delegation.API_key
` và 
`delegation.model

. Điều đó sẽ gửi các tác nhân phụ trực tiếp đến điểm cuối tương thích OpenAI đó và được ưu tiên hơn 
`delegation.provider

. Nếu 
`delegation.API_key
` bị bỏ qua, Hermes chỉ quay lại 
`OpenAI_API_KEY

.

**Giao thức dây (
`API_mode

):** Hermes tự động phát hiện giao thức dây từ 
`delegation.base_url
` (ví dụ: các đường dẫn kết thúc bằng 

/Anthropic
` → 
`Anthropic_messages

; Codex / tên máy chủ Anthropic / Kimi-coding giữ nguyên khả năng phát hiện hiện có của chúng). Đối với các điểm cuối, phương pháp phỏng đoán không thể phân loại — ví dụ: các proxy Azure AI Foundry, MiniMax, Zhipu GLM hoặc LiteLLM phía trước phần phụ trợ có hình dạng Anthropic — đặt 
`delegation.API_mode
` rõ ràng thành một trong các 
`chat_completions

, 
`Codex_responses
` hoặc 
`Anthropic_messages

. Để trống (mặc định) để tiếp tục tự động phát hiện.Nhà cung cấp ủy quyền sử dụng cùng độ phân giải thông tin xác thực như khi khởi động CLI/gateway. Tất cả các nhà cung cấp đã định cấu hình đều được hỗ trợ: 
`OpenRouter

, 
`nous

, 
`copilot

, 
`zai

, 
`Kimi-coding

, 
`MiniMax

, 
`MiniMax-cn

. Khi nhà cung cấp được đặt, hệ thống sẽ tự động phân giải chính xác URL cơ sở, khóa API và chế độ API — không cần nối dây thông tin xác thực thủ công.

**Ưu tiên:** 
`delegation.base_url
` trong cấu hình → 
`delegation.provider
` trong cấu hình → nhà cung cấp chính (kế thừa). 
`delegation.model
` trong cấu hình → mô hình gốc (được kế thừa). Chỉ đặt 
`model
` mà không có 
`provider
` chỉ thay đổi tên mô hình trong khi vẫn giữ thông tin xác thực của cha mẹ (hữu ích cho việc chuyển đổi mô hình trong cùng một nhà cung cấp như OpenRouter).

**Chiều rộng và chiều sâu:** 
`max_concurrent_children
` giới hạn số lượng tác nhân phụ chạy song song trên mỗi đợt (
`3
` mặc định, tầng 1, không có trần). Cũng có thể được đặt thông qua 
`DELEGATION_MAX_CONCURRENT_CHILDREN
` env var. Khi mô hình gửi mảng 
`tasks
` dài hơn giới hạn, 
`delegate_task
` sẽ trả về lỗi công cụ giải thích giới hạn thay vì cắt ngắn âm thầm. 
`max_spawn_depth
` kiểm soát độ sâu của cây ủy quyền (được kẹp ở mức 1-3). Ở 
`1
` mặc định, việc ủy ​​quyền không thay đổi: con cái không thể sinh ra cháu và việc chuyển 
`role="orchestrator"
` sẽ âm thầm xuống cấp thành 
`leaf

. Nâng lên 
`2
` để con của người điều phối có thể sinh ra các cháu lá; 
`3
` dành cho cây ba cấp. Đại lý chọn tham gia điều phối mỗi cuộc gọi thông qua 
`role="orchestrator"

; 
`orchestrator_enabled: false
` buộc mọi đứa trẻ phải quay trở lại lá. Quy mô chi phí tăng gấp bội — tại 
`max_spawn_depth: 3
` với 
`max_concurrent_children: 3

, cây có thể đạt 3×3×3 = 27 tác nhân lá đồng thời. Xem [Subagent Delegation → Depth Limit and Nested Orchestration](features/delegation.md#depth-limit-and-nested-orchestration) để biết cách sử dụng.

## Làm rõ

Định cấu hình hành vi nhắc làm rõ:

``` yaml
clarify:
  timeout: 120                 # Seconds to wait for user clarification response

`

## Tệp ngữ cảnh (SOUL.md, AGENTS.md)

Hermes sử dụng hai phạm vi ngữ cảnh khác nhau:

| Tập tin | Mục đích | Phạm vi |
|------|----------|-------|
| 
`SOUL.md
` | **Danh tính tác nhân chính** — xác định ai là tác nhân (vị trí số 1 trong lời nhắc hệ thống) |

~/.Hermes/SOUL.md
` hoặc 

$Hermes_HOME/SOUL.md
` |
| 

.Hermes.md
` / 
`Hermes.md
` | Hướng dẫn dành riêng cho dự án (ưu tiên cao nhất) | Đi tới git root |
| 
`AGENTS.md
` | Hướng dẫn dành riêng cho dự án, quy ước mã hóa | Đi bộ thư mục đệ quy |
| 
`Claude.md
` | Tệp ngữ cảnh Mã Claude (cũng được phát hiện) | Chỉ thư mục làm việc |
| 

.Cursorrules
` | Quy tắc IDE con trỏ (cũng được phát hiện) | Chỉ thư mục làm việc |
| 

.Cursor/rules/*.mdc
` | Tệp quy tắc con trỏ (cũng được phát hiện) | Chỉ thư mục làm việc |
- **SOUL.md** là danh tính chính của đại lý. Nó chiếm vị trí số 1 trong dấu nhắc hệ thống, thay thế hoàn toàn danh tính mặc định tích hợp sẵn. Chỉnh sửa nó để tùy chỉnh đầy đủ người đại diện là ai.

- Nếu SOUL.md bị thiếu, trống hoặc không thể tải được, Hermes sẽ quay trở lại danh tính mặc định được tích hợp sẵn.
- **Tệp ngữ cảnh dự án sử dụng hệ thống ưu tiên** — chỉ tải MỘT loại (trận đầu tiên thắng): 

.Hermes.md
` → 
`AGENTS.md
` → 
`Claude.md
` → 

.Cursorrules

. SOUL.md luôn được tải độc lập.
- **AGENTS.md** có tính phân cấp: nếu thư mục con cũng có AGENTS.md thì tất cả đều được kết hợp.
- Hermes tự động tạo 
`SOUL.md
` mặc định nếu chưa tồn tại.
- Tất cả các tệp ngữ cảnh được tải đều được giới hạn ở 20.000 ký tự với tính năng cắt bớt thông minh.

Xem thêm:
- [Personality & SOUL.md](/docs/user-guide/features/personality)
- [Context Files](/docs/user-guide/features/context-files)

## Thư mục làm việc

| Bối cảnh | Mặc định |
|----------|----------|
| **CLI (
`Hermes

)** | Thư mục hiện tại nơi bạn chạy lệnh |
| **Cổng nhắn tin** | Thư mục chính 

~
` (ghi đè bằng 
`MESSAGING_CWD

) |
| **Docker / Singularity / Modal / SSH** | Thư mục chính của người dùng bên trong vùng chứa hoặc máy từ xa |

Ghi đè thư mục làm việc:

`
``` bash

# In ~/.Hermes/.env or ~/.Hermes/config.yaml:
MESSAGING_CWD=/home/myuser/projects    # Gateway sessions
TERMINAL_CWD=/workspace                # All terminal sessions

`
`