Cấu hình

Tất 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

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

mẹo

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):

Đối số CLI — ví dụ: hermes chat --model anthropic/claude-sonnet-4 (ghi đè mỗi lần gọi)
** ~/.hermes/config.yaml ** — tệp cấu hình chính cho tất cả cài đặt không bí mật
** ~/.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)
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

Quy tắc ngón tay cái

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}:

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, phần 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 Nhà cung cấp AI.

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

Hermes hỗ trợ sáu 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, không gian làm việc Daytona hoặc bộ chứa Singularity/Apptainer.

terminal:
  backend: local    

# local 

| docker | ssh | modal 

| daytona | singularity
  cwd: "."          

# Working directory ("." = current dir for local, "/root" for containers)
  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 và Daytona, 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 hộp cát trực tiếp, không gian PID hoặc các tiến trình nền sẽ vẫn chạy sau đó.

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	Docker container	Đầ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ý
đ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.

terminal:
  backend: local

cảnh báo

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).

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  

# Mount launch dir into /workspace
  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

  

# 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

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).

Vòng đời của vùng chứa: Mỗi phiên bắt đầu một vùng chứa tồn tại lâu dài ( docker run -d ... sleep 2h ). Các lệnh chạy qua docker exec bằng shell đăng nhập. Khi dọn dẹp, thùng chứa sẽ dừng lại và được lấy ra.

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

--cap-drop ALL chỉ có DAC_OVERRIDE , CHOWN , FOWNER được thêm lại
--security-opt no-new-privileges
--pids-limit 256
Tmpfs có giới hạn kích thước 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.

terminal:
  backend: ssh
  persistent_shell: true           

# Keep a long-lived bash session (default: true)

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

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 . Persistent shell duy trì một tiến trình bash -l duy nhất 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ức

Chạy các lệnh trong hộp cát đám mây Modal. 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.

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. Hỗ trợ dừng/tiếp tục để duy trì.

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: DAYTONA_API_KEY biến môi trường.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 đơn lẻ/Apptainer

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

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 Scratch: Đã 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ủ.
Singularity — 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.

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] .

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   

# Read-write (default)
    - "/home/user/datasets:/data:ro"              

# Read-only
    - "/home/user/outputs:/outputs"               

# Agent writes, you read

Đ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

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 mã đó vào terminal.docker_forward_env .

terminal:
  backend: docker
  docker_forward_env:
    - "GITHUB_TOKEN"
    - "NPM_TOKEN"

Hermes xử lý 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 .

cảnh báo

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.

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 :

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 sau /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ị tắt, /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 tồn ranh giới hộp cát
true 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ộ.

terminal:
  persistent_shell: true   

# default — enables persistent shell for SSH

Để vô hiệu hóa:

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ộ:

export TERMINAL_LOCAL_PERSISTENT=true

ghi chú

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 Thực thi mã và phần Thiết bị đầu cuối của README để 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 .

skills:
  config:
    wiki:
      path: ~/wiki          

# Used by the llm-wiki skill

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:

hermes config set skills.config.wiki.path ~/my-research-wiki

Để biết chi tiết về cách khai báo cài đặt cấu hình trong kỹ năng của riêng bạn, hãy xem Tạo kỹ năng — Cài đặt cấu hình.

Cấu hình bộ nhớ

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ệpKiể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 vào cửa sổ ngữ cảnh.

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:

# 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.

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:

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 công việc thông qua .worktreeinclude trong thư mục gốc của bạn:

# .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 đủ

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
  summary_model: "google/gemini-3-flash-preview"    

# Model for summarization
  summary_provider: "auto"                          

# Provider: "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                            

# Custom OpenAI-compatible endpoint (overrides provider)

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:

compression:
  enabled: true
  threshold: 0.50

Sử dụng nhà cung cấp có sẵn đầu tiên (OpenRouter → Nous → Codex) với Gemini Flash.

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

compression:
  summary_provider: nous
  summary_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.):

compression:
  summary_model: glm-4.7
  summary_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

`summary_provider`	`summary_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)

summary_model phải hỗ trợ độ dài ngữ cảnh ít nhất bằng mô hình chính của bạn vì nó nhận được toàn bộ phần giữa của cuộc hội thoại để nén.

Á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.

agent:
  max_turns: 90                

# Max iterations per conversation turn (default: 90)

Áp lực ngân sách được bật theo mặc định. Tác nhân coi các cảnh báo một cách tự nhiên là một phần của 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.

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:

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 Nhóm thông tin xác thực để biết tài liệu đầy đủ.

Mô hình phụ trợ

Hermes sử dụng các mô hình "phụ trợ" nhẹ cho các tác vụ phụ như phân tích hình ảnh, tóm tắt trang web và phân tích ảnh chụp màn hình trình duyệt. Theo mặc định, những ứng dụng này sử dụng Gemini Flash thông qua tính năng tự động phát hiện — bạn không cần phải định cấu hình bất kỳ thứ gì.

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ỉ provider được đặt, Hermes sử dụng URL cơ sở và xác thực tích hợp của nhà cung cấp đó.Nhà cung cấp hiện có: auto , openrouter , nous , codex , copilot , anthropic , main , zai , kimi-coding , minimax , bất kỳ nhà cung cấp nào đã đăng ký trong [nhà cung cấp] register](/docs/reference/environment-variables) 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" ).

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

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: 30                

# seconds — LLM API call; increase for slow local vision models
    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

  

# Session search — summarizes past session matches
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  

# 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

  

# Memory flush — summarizes conversation for persistent memory
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

mẹo

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 30 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 thời gian này cho các kết nối chậm hoặc máy chủ hình ảnh tự lưu trữ.

thông tin

Nén ngữ cảnh có khối compression: cấp cao nhất của riêng nó với summary_provider , summary_model và summary_base_url — xem Nén ngữ cảnh ở trên. Mô hình dự phòng sử dụng khối fallback_model: — xem Mô hình dự phòng. Cả ba đều tuân theo cùng một mẫu nhà cung cấp/mô hình/base_url.

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:

auxiliary:
  vision:
    model: "openai/gpt-4o"

Hoặc thông qua biến môi trường (trong ~/.hermes/.env ):

AUXILIARY_VISION_MODEL=openai/gpt-4o

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

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
`"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.	Thông tin xác thực điểm cuối tùy chỉnh + URL cơ sở

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" đối với API cục bộ/tự lưu trữ):

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 một tác vụ phụ trợ đến một đ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:

# 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):

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):

auxiliary:
  vision:
    provider: "codex"     

# uses your ChatGPT OAuth token
    

# model defaults to gpt-5.3-codex (supports vision)

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

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 tên (ví dụ: beans ), nhà cung cấp tích hợp như openrouter hay điểm cuối OPENAI_BASE_URL cũ.

mẹo

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.

cảnh báo

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.

mẹo

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:

agent:
  reasoning_effort: ""   

# empty = medium (default). Options: xhigh (max), high, medium, low, minimal, none

Khi không được đặt (mặc định), nỗ lực suy luận sẽ mặc định ở mức "trung bình" — một 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 (đặc biệt là dòng GPT) đô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ụ. Việc thực thi sử dụng công cụ đưa ra hướng dẫn hướng mô hình quay trở lại gọi các công cụ thực sự.

agent:
  tool_use_enforcement: "auto"   

# "auto" 

| true  | false  | ["model-substring", ...]

Giá trị	Hành vi
`"auto"` (mặc định)	Đã bật cho các kiểu máy GPT ( `gpt-` , `openai/gpt-` ) và bị tắt cho tất cả các kiểu máy khác.
`true`	Luôn được kích hoạt cho tất cả các kiểu máy.
`false`	Luôn luôn bị vô hiệu hóa.
`["gpt-", "o1-", "custom-model"]`	Chỉ được bật cho các mẫu có tên chứa một trong các chuỗi con được liệt kê.

Khi được bật, lời nhắc hệ thống sẽ bao gồm hướng dẫn nhắc nhở mô hình thực hiện lệnh gọi công cụ thực tế thay vì mô tả những gì nó sẽ làm. Điều này minh bạch đối với người dùng và không ảnh hưởng đến các mô hình đã sử dụng các công cụ một cách đáng tin cậy.

Cấu hình TTS

tts:
  provider: "edge"              

# "edge" 

| "elevenlabs"  | "openai"  | "neutts"
  edge:
    voice: "en-US-AriaNeural"   

# 322 voices, 74 languages
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              

# alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  

# Override for OpenAI-compatible TTS endpoints
  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).

Cài đặt hiển thị

display:
  tool_progress: all      

# off 

| new  | all  | verbose
  tool_progress_command: false  

# Enable /verbose slash command in messaging gateway
  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
  tool_preview_length: 0  

# Max chars for tool call previews (0 = no limit, show full paths/commands)

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 đủ

Quyền riêng tư

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)

stt:
  provider: "local"            

# "local" 

| "groq" | "openai"
  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:

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)

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
  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 Chế độ giọng nói để 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

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)

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

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ị tắt một cách nhẹ nhàng cho phiên đó mà không có tin nhắn tràn ngập.

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.

ghi chú

Truyền phát bị tắt theo mặc định. Kích hoạt nó trong ~/.hermes/config.yaml để thử trải nghiệm người dùng 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:

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 mình bên trong chuỗi.

Để biết chi tiết và ví dụ về hành vi, hãy xem Phiên và Hướng dẫn 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:

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 gửi tin nhắn trực tiếp 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 — không sử dụng mã thông báo, thực thi ngay lập tức. Đặc biệt hữu ích từ các nền tảng nhắn tin (Telegram, Discord, v.v.) để kiểm tra máy chủ nhanh chóng hoặc các tập lệnh tiện ích.

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

Cách sử dụng: nhập /status , /disk , /update hoặc /gpu trong CLI hoặc bất kỳ nền tảng nhắn tin nào. Lệnh 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.

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 — chỉ hỗ trợ exec (chạy lệnh shell); 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

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:

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ụ thực thi mã Python được đóng hộp cát:

code_execution:
  timeout: 300                 

# Max execution time in seconds
  max_tool_calls: 50           

# Max tool calls within code execution

Phần cuối của Tìm kiếm trên Web

Các công cụ web_search , web_extract và web_crawl hỗ trợ bốn 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 :

web:
  backend: firecrawl    

# firecrawl 

| parallel  | tavily  | exa

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`	✔	✔	✔
Song song	`PARALLEL_API_KEY`	✔	✔	—
Tavily	`TAVILY_API_KEY`	✔	✔	✔
Exa	`EXA_API_KEY`	✔	✔	—

Lựa chọn phần phụ trợ: Nếu không đặt web.backend, 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 EXA_API_KEY thì 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 thì Parallel sẽ được sử dụng. Nếu không thì Firecrawl là mặc định.

Firecrawl tự lưu trữ: Đặt FIRECRAWL_API_URL để trỏ đến phiên bản của riêng bạn. Khi URL tùy chỉnh được đặt, khóa API sẽ trở thành tùy chọn (đặt USE_DB_AUTHENTICATION=false 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 ).

Trình duyệt

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

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/
  camofox:
    managed_persistence: false   

# When true, Camofox sessions persist cookies/logins across restarts

Bộ công cụ trình duyệt hỗ trợ nhiều nhà cung cấp. Xem Trang tính năng trình duyệt để 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 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.

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ủ.

Bất hòa

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

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 bằng @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 trả lời mọi tin nhắn mà không yêu cầu đề cập.
auto_thread — khi true (mặc định), các lượt đề 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ư chuỗi 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:

security:
  redact_secrets: true           

# Redact API key patterns in tool output and logs
  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 — 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 nó đi vào ngữ cảnh và nhật ký hội thoại.
tirith_enabled — khi true , các lệnh đầu cuối được quét bởi Tirith 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ứ mười. 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ý:

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 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 tàng:

```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.

cảnh báo

Cài đặt approvals.mode: off sẽ tắt 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 Điểm kiểm tra & Khôi phục để biết chi tiết.

checkpoints:
  enabled: true                  

# Enable automatic checkpoints (also: hermes --checkpoints)
  max_snapshots: 50              

# Max checkpoints to keep per directory

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:

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)

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 với 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.

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 (được 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).

Làm rõ

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

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 một SOUL.md mặc định nếu nó 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:

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:

# In ~/.hermes/.env or ~/.hermes/config.yaml:
MESSAGING_CWD=/home/myuser/projects    

# Gateway sessions
TERMINAL_CWD=/workspace                

# All terminal sessions

Cấu trúc thư mục

Quản lý cấu hình

Ưu tiên cấu hình

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

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

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

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

Phần cuối của Docker​

Phần cuối SSH​

Phần cuối phương thức​

Phần cuối của Daytona​

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

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

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

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

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

Vỏ liên tục​

Cài đặt kỹ năng

Cấu hình bộ nhớ

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

Nén ngữ cảnh

Tham khảo đầy đủ​

Các thiết lập phổ biến​

Cách ba nút tương tác​

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

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

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

Mô hình phụ trợ

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

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

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

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

Các thiết lập phổ biến​

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

Nỗ lực lý luận

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

Cấu hình TTS

Cài đặt hiển thị

Quyền riêng tư

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

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

Đang phát trực tuyến

Truyền phát CLI​

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

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

Hành vi DM trái phép

Lệnh nhanh

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

Thực thi mã

Phần cuối của Tìm kiếm trên Web

Trình duyệt

Múi giờ

Bất hòa

Bảo mật

Danh sách chặn trang web

Điểm kiểm tra

Phái đoàn

Làm rõ

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

Thư mục làm việc

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

Phần cuối cục bộ

Phần cuối của Docker

Phần cuối SSH

Phần cuối phương thức

Phần cuối của Daytona

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

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

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

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

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

Vỏ liên tục

Tham khảo đầy đủ

Các thiết lập phổ biến

Cách ba nút tương tác

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

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

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

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

Các thiết lập phổ biến

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

Truyền phát CLI

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