Hướng dẫn 7: Tệp Cấu Hình

Chào mừng trở lại, những người quản lý agent! Trong hướng dẫn này, chúng ta sẽ đi sâu vào trái tim của Hermes: các tệp cấu hình. Nếu bạn từng cảm thấy lạc lối giữa biển YAML và biến môi trường, đừng lo—chúng ta sẽ làm cho việc này trở nên dễ dàng nhất có thể.

Căn Cứ Chính Của Hermes

Mọi thứ đều nằm trong ~/.hermes/. Hãy coi nó như căn hộ của agent của bạn. Đây là những gì bên trong:

~/.hermes/
├── config.yaml     # Cài đặt (model, terminal, TTS, nén, v.v.)
├── .env            # Khóa API và bí mật
├── auth.json       # Thông tin xác thực OAuth provider (Nous Portal, v.v.)
├── SOUL.md         # Danh tính agent chính (vị trí #1 trong system prompt)
├── memories/       # Bộ nhớ bền vững (MEMORY.md, USER.md)
├── skills/         # Kỹ năng do agent tạo (quản lý qua công cụ skill_manage)
├── cron/           # Các tác vụ theo lịch
├── sessions/       # Các phiên gateway
└── logs/           # Nhật ký (errors.log, gateway.log — bí mật được tự động che)

Con Đường Dễ Nhất: Thiết Lập Một Lệnh

Trước khi đi sâu vào chi tiết, đây là một mẹo chuyên nghiệp: chạy hermes setup --portal. Một lần OAuth sẽ cung cấp cho bạn một model provider và cả bốn công cụ Tool Gateway mà không cần đụng đến bất kỳ tệp YAML nào. Người đăng ký Portal cũng được giảm 10% cho các provider tính phí theo token. Đây là cách lười biếng để bắt đầu, và chúng tôi yêu thích nó.

Quản Lý Cấu Hình Của Bạn

Hermes cung cấp cho bạn một bộ công cụ đầy đủ để quản lý cài đặt. Dưới đây là các lệnh bạn sẽ sử dụng hàng ngày:

hermes config              # Xem cấu hình hiện tại
hermes config edit         # Mở config.yaml trong trình soạn thảo của bạn
hermes config get KEY      # In ra một giá trị đã được phân giải
hermes config set KEY VAL  # Đặt một giá trị cụ thể
hermes config unset KEY    # Xóa một giá trị do người dùng đặt
hermes config check        # Kiểm tra các tùy chọn còn thiếu (sau khi cập nhật)
hermes config migrate      # Thêm tương tác các tùy chọn còn thiếu

Dưới đây là một số ví dụ thực tế:

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # Lưu vào .env

Mẹo kỳ diệu: hermes config set tự động định tuyến các giá trị đến đúng tệp. Khóa API sẽ vào .env, mọi thứ khác sẽ vào config.yaml. Không còn phải đoán nữa!

Điều Gì Thắng Khi Có Xung Đột?

Hermes phân giải cài đặt theo thứ tự sau (ưu tiên cao nhất trước):

Đối số CLI — như hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — tệp cấu hình chính của bạn
~/.hermes/.env — cho các bí mật (khóa API, token, mật khẩu)
Giá trị mặc định tích hợp — các giá trị mã cứng an toàn

Quy tắc chung: Bí mật nằm trong .env. Mọi thứ khác nằm trong config.yaml. Khi cả hai đều được đặt, config.yaml thắng cho các cài đặt không phải 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 cũng hoạt động: url: "${HOST}:${PORT}". Nếu một biến không được đặt, placeholder sẽ giữ nguyên và một cảnh báo được ghi vào nhật ký. Cú pháp kiểu Cursor ${env:VAR_NAME} cũng hoạt động, vì vậy bạn có thể sao chép các đoạn mã từ cấu hình Cursor hoặc Claude mà không cần thay đổi.

Thời Gian Chờ Của Provider

Bạn có thể đặt thời gian chờ cho từng provider và từng model:

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

Cũng có stale_timeout_seconds để phát hiện các cuộc gọi không phát trực tiếp bị treo. Các cài đặt này ghi đè các biến môi trường cũ HERMES_API_TIMEOUT và HERMES_API_CALL_STALE_TIMEOUT.

Giới Hạn Thời Gian Chạy

Đối với các bề mặt máy chủ chạy lâu dài (gateway, hermes serve --isolated), bạn có thể đặt giới hạn file descriptor:

runtime:
  nofile_soft_limit: 4096

Giá trị mặc định là 4096. Đặt nó thành 0, false hoặc null để vô hiệu hóa việc điều chỉnh.

Hành Vi Cập Nhật

Các cài đặt cập nhật nằm dưới mục updates trong config.yaml:

updates:
  pre_update_backup: quick

Tổng Kết

Đó là chuyến tham quan cấu hình! Hãy nhớ: hermes setup --portal cho con đường dễ dàng, hermes config set cho các thay đổi nhanh chóng, và giữ bí mật trong .env. Agent của bạn sẽ cảm ơn bạn.

Tiếp theo: chúng ta sẽ khám phá các AI provider và cách kết nối các model yêu thích của bạn. Hãy đón chờ nhé!