Câu hỏi thường gặp & Khắc phục sự cố

Câu trả lời nhanh và cách khắc phục cho các câu hỏi và vấn đề phổ biến nhất.

Câu hỏi thường gặp

Nhà cung cấp LLM nào hợp tác với Hermes?

Hermes Agent hoạt động với mọi API tương thích với OpenAI. Các nhà cung cấp được hỗ trợ bao gồm:

OpenRouter — truy cập hàng trăm mô hình thông qua một khóa API (được khuyến nghị để linh hoạt)
Nous Portal — Điểm cuối suy luận riêng của Nous Research
OpenAI — GPT-4o, o1, o3, v.v.
Nhân loại — Mô hình Claude (thông qua OpenRouter hoặc proxy tương thích)
Google — Mô hình Gemini (thông qua OpenRouter hoặc proxy tương thích)
z.ai / ZhipuAI — Mô hình GLM
Kimi / Moonshot AI — Người mẫu Kimi
MiniMax — điểm cuối toàn cầu và Trung Quốc
Mô hình địa phương — qua Ollama, vLLM, llama.cpp, SGLang hoặc bất kỳ máy chủ tương thích OpenAI nào

Đặt nhà cung cấp của bạn bằng hermes model hoặc bằng cách chỉnh sửa ~/.hermes/.env. Xem tài liệu tham khảo Biến môi trường để biết tất cả các khóa của nhà cung cấp.

Nó có hoạt động trên Windows không?

Không phải nguyên bản. Hermes Agent yêu cầu môi trường giống Unix. Trên Windows, cài đặt WSL2 và chạy Hermes từ bên trong nó. Lệnh cài đặt tiêu chuẩn hoạt động hoàn hảo trong WSL2:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Dữ liệu của tôi có được gửi đi đâu không?

Lệnh gọi API chỉ được gửi đến nhà cung cấp LLM mà bạn định cấu hình (ví dụ: OpenRouter, phiên bản Ollama cục bộ của bạn). Đại lý Hermes không thu thập dữ liệu đo từ xa, dữ liệu sử dụng hoặc phân tích. Các cuộc trò chuyện, trí nhớ và kỹ năng của bạn được lưu trữ cục bộ trong ~/.hermes/.

Tôi có thể sử dụng ngoại tuyến / với các mẫu máy cục bộ không?

Đúng. Chạy mô hình hermes, chọn Điểm cuối tùy chỉnh và nhập URL máy chủ của bạn:

hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 32768   ← set this to match your server's actual context window

Hoặc định cấu hình trực tiếp trong config.yaml:

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

Hermes vẫn duy trì điểm cuối, nhà cung cấp và URL cơ sở trong config.yaml để nó vẫn tồn tại sau khi khởi động lại. Nếu máy chủ cục bộ của bạn đã tải chính xác một mô hình, /model custom sẽ tự động phát hiện mô hình đó. Bạn cũng có thể đặt nhà cung cấp: custom trong config.yaml — đó là nhà cung cấp hạng nhất, không phải bí danh cho bất kỳ nhà cung cấp nào khác.

Tính năng này hoạt động với Ollama, vLLM, máy chủ llama.cpp, SGLang, LocalAI và các máy chủ khác. Xem Hướng dẫn cấu hình để biết chi tiết.

Ollama users

Nếu bạn đặt num_ctx tùy chỉnh trong Ollama (ví dụ: ollama run --num_ctx 16384), hãy đảm bảo đặt độ dài ngữ cảnh phù hợp trong Hermes — /api/show của Ollama báo cáo ngữ cảnh tối đa của mô hình, chứ không phải num_ctx hiệu quả mà bạn đã định cấu hình.

###Nó có giá bao nhiêu?

Bản thân Hermes Agent miễn phí và là nguồn mở (giấy phép MIT). Bạn chỉ trả tiền cho việc sử dụng API LLM từ nhà cung cấp bạn đã chọn. Các mô hình địa phương hoàn toàn miễn phí để chạy.

Nhiều người có thể sử dụng một phiên bản không?

Đúng. Cổng nhắn tin cho phép nhiều người dùng tương tác với cùng một phiên bản Hermes Agent thông qua Telegram, Discord, Slack, WhatsApp hoặc Home Assistant. Quyền truy cập được kiểm soát thông qua danh sách cho phép (ID người dùng cụ thể) và ghép nối DM (người dùng đầu tiên gửi tin nhắn yêu cầu quyền truy cập).

###Sự khác biệt giữa trí nhớ và kỹ năng là gì?

Bộ nhớ lưu trữ sự kiện — những điều mà nhân viên biết về bạn, dự án và sở thích của bạn. Ký ức được truy xuất tự động dựa trên mức độ liên quan.
Kỹ năng lưu trữ thủ tục — hướng dẫn từng bước về cách thực hiện mọi việc. Các kỹ năng được thu hồi khi đặc vụ gặp một nhiệm vụ tương tự.

Cả hai đều tồn tại qua các phiên. Xem Memory và Skills để biết chi tiết.

Tôi có thể sử dụng nó trong dự án Python của riêng mình không?

Đúng. Nhập lớp AIAgent và sử dụng Hermes theo chương trình:

from run_agent import AIAgent

agent = AIAgent(model="openrouter/nous/hermes-3-llama-3.1-70b")
response = agent.chat("Explain quantum computing briefly")

Xem Hướng dẫn về Thư viện Python để biết cách sử dụng API đầy đủ.

Khắc phục sự cố

Sự cố cài đặt

`hermes: không tìm thấy lệnh` sau khi cài đặt

Lý do: Shell của bạn chưa tải lại PATH đã cập nhật.

Giải pháp:

# Reload your shell profile
source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# Or start a new terminal session

Nếu nó vẫn không hoạt động, hãy xác minh vị trí cài đặt:

which hermes
ls ~/.local/bin/hermes

mẹo

Trình cài đặt thêm ~/.local/bin vào PATH của bạn. Nếu bạn sử dụng cấu hình shell không chuẩn, hãy thêm export PATH="$HOME/.local/bin:$PATH" theo cách thủ công.

####Phiên bản Python quá cũ

Lý do: Hermes yêu cầu Python 3.11 trở lên.

Giải pháp:

python3 --version   # Check current version

# Install a newer Python
sudo apt install python3.12   # Ubuntu/Debian
brew install python@3.12      # macOS

Trình cài đặt tự động xử lý việc này — nếu bạn thấy lỗi này trong quá trình cài đặt thủ công, trước tiên hãy nâng cấp Python.

`uv: không tìm thấy lệnh`

Lý do: Trình quản lý gói uv chưa được cài đặt hoặc không có trong PATH.

Giải pháp:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Lỗi từ chối quyền trong quá trình cài đặt

Lý do: Không đủ quyền để ghi vào thư mục cài đặt.

Giải pháp:

# Don't use sudo with the installer — it installs to ~/.local/bin
# If you previously installed with sudo, clean up:
sudo rm /usr/local/bin/hermes
# Then re-run the standard installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Vấn đề về nhà cung cấp và mô hình

####Khóa API không hoạt động

Lý do: Key bị thiếu, hết hạn, đặt sai hoặc sai nhà cung cấp.

Giải pháp:

# Check your configuration
hermes config show

# Re-configure your provider
hermes model

# Or set directly
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

cảnh báo

Đảm bảo khóa khớp với nhà cung cấp. Khóa OpenAI sẽ không hoạt động với OpenRouter và ngược lại. Kiểm tra ~/.hermes/.env để tìm các mục nhập xung đột.

####Không có mẫu máy/không tìm thấy mẫu máy

Lý do: Mã định danh mẫu máy không chính xác hoặc không có sẵn trên nhà cung cấp của bạn.

Giải pháp:

# List available models for your provider
hermes model

# Set a valid model
hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b

# Or specify per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

Giới hạn tỷ lệ (429 lỗi)

Lý do: Bạn đã vượt quá giới hạn tốc độ của nhà cung cấp.

Giải pháp: Đợi một lát và thử lại. Để sử dụng lâu dài, hãy cân nhắc:

Nâng cấp gói nhà cung cấp của bạn
Chuyển sang model hoặc nhà cung cấp khác
Sử dụng hermes chat --provider <alternative> để định tuyến đến một chương trình phụ trợ khác

Đã vượt quá độ dài ngữ cảnh

Lý do: Cuộc trò chuyện đã quá dài so với cửa sổ ngữ cảnh của mô hình hoặc Hermes đã phát hiện thấy độ dài ngữ cảnh không chính xác cho mô hình của bạn.

Giải pháp:

# Compress the current session
/compress

# Or start a fresh session
hermes chat

# Use a model with a larger context window
hermes chat --model openrouter/google/gemini-3-flash-preview

Nếu điều này xảy ra trong cuộc trò chuyện dài đầu tiên, Hermes có thể đã hiểu sai độ dài ngữ cảnh cho mô hình của bạn. Kiểm tra những gì nó phát hiện:

Nhìn vào dòng khởi động CLI - nó hiển thị độ dài ngữ cảnh được phát hiện (ví dụ: 📊 Giới hạn ngữ cảnh: 128000 mã thông báo). Bạn cũng có thể kiểm tra bằng /use trong một phiên.

Để sửa lỗi phát hiện ngữ cảnh, hãy đặt nó một cách rõ ràng:

# In ~/.hermes/config.yaml
model:
  default: your-model-name
  context_length: 131072  # your model's actual context window

Hoặc đối với các điểm cuối tùy chỉnh, hãy thêm nó vào mỗi mô hình:

custom_providers:
  - name: "My Server"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768

Xem Phát hiện độ dài bối cảnh để biết cách hoạt động của tính năng tự động phát hiện và tất cả các tùy chọn ghi đè.

Sự cố thiết bị đầu cuối

Lệnh bị chặn vì nguy hiểm

Lý do: Hermes đã phát hiện thấy một lệnh có khả năng phá hoại (ví dụ: rm -rf, DROP TABLE). Đây là một tính năng an toàn.

Giải pháp: Khi được nhắc, hãy xem lại lệnh và nhập y để phê duyệt. Bạn cũng có thể:

Yêu cầu đại lý sử dụng giải pháp thay thế an toàn hơn
Xem danh sách đầy đủ các mẫu nguy hiểm trong Tài liệu bảo mật

mẹo

Điều này đang hoạt động như dự định - Hermes không bao giờ âm thầm thực hiện các lệnh phá hoại. Lời nhắc phê duyệt hiển thị cho bạn chính xác những gì sẽ thực thi.

`sudo` không hoạt động qua cổng nhắn tin

Lý do: Cổng nhắn tin chạy mà không có thiết bị đầu cuối tương tác, vì vậy sudo không thể nhắc nhập mật khẩu.

Giải pháp:

Tránh sudo trong tin nhắn — yêu cầu nhân viên tìm giải pháp thay thế
Nếu bạn phải sử dụng sudo, hãy định cấu hình sudo không mật khẩu cho các lệnh cụ thể trong /etc/sudoers
Hoặc chuyển sang giao diện terminal cho các tác vụ quản trị: hermes chat

Chương trình phụ trợ Docker không kết nối

Lý do: Docker daemon không chạy hoặc người dùng thiếu quyền.

Giải pháp:

# Check Docker is running
docker info

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker run hello-world

Sự cố nhắn tin

####Bot không trả lời tin nhắn

Lý do: Bot hiện không chạy, không được cấp phép hoặc người dùng của bạn không có trong danh sách cho phép.

Giải pháp:

# Check if the gateway is running
hermes gateway status

# Start the gateway
hermes gateway start

# Check logs for errors
cat ~/.hermes/logs/gateway.log | tail -50

Tin nhắn không gửi được

Lý do: Sự cố mạng, mã thông báo bot đã hết hạn hoặc cấu hình webhook nền tảng sai.

Giải pháp:

Xác minh mã thông báo bot của bạn hợp lệ với thiết lập cổng hermes
Kiểm tra nhật ký cổng: cat ~/.hermes/logs/gateway.log | đuôi -50
Đối với các nền tảng dựa trên webhook (Slack, WhatsApp), hãy đảm bảo máy chủ của bạn có thể truy cập công khai

Nhầm lẫn về danh sách cho phép — ai có thể nói chuyện với bot?

Lý do: Chế độ ủy quyền xác định ai có quyền truy cập.

Giải pháp:

Chế độ	Nó hoạt động như thế nào
Danh sách cho phép	Chỉ ID người dùng được liệt kê trong cấu hình mới có thể tương tác
Ghép nối DM	Người dùng đầu tiên nhắn tin trong DM yêu cầu quyền truy cập độc quyền
Mở	Bất cứ ai cũng có thể tương tác (không được khuyến khích sản xuất)

Định cấu hình trong ~/.hermes/config.yaml trong cài đặt cổng của bạn. Xem Tài liệu nhắn tin.

Cổng không khởi động

Lý do: Thiếu phần phụ thuộc, xung đột cổng hoặc mã thông báo bị định cấu hình sai.

Giải pháp:

# Install messaging dependencies
pip install "hermes-agent[telegram]"   # or [discord], [slack], [whatsapp]

# Check for port conflicts
lsof -i :8080

# Verify configuration
hermes config show

macOS: Node.js/ffmpeg/các công cụ khác không được cổng kết nối tìm thấy

Nguyên nhân: các dịch vụ launchd kế thừa một PATH tối thiểu (/usr/bin:/bin:/usr/sbin:/sbin) không bao gồm Homebrew, nvm, Cargo hoặc các thư mục công cụ do người dùng cài đặt khác. Điều này thường phá vỡ cầu nối WhatsApp (không tìm thấy nút) hoặc phiên âm giọng nói (không tìm thấy ffmpeg).

Giải pháp: Cổng ghi lại PATH shell của bạn khi bạn chạy cài đặt cổng hermes. Nếu bạn đã cài đặt các công cụ sau khi thiết lập cổng, hãy chạy lại quá trình cài đặt để ghi lại PATH đã cập nhật:

hermes gateway install    # Re-snapshots your current PATH
hermes gateway start      # Detects the updated plist and reloads

Bạn có thể xác minh số nguyên có PATH chính xác:

/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.hermes.gateway.plist

Vấn đề về hiệu suất

####Phản hồi chậm

Lý do: Model lớn, máy chủ API ở xa hoặc lời nhắc hệ thống nặng với nhiều công cụ.

Giải pháp:

Thử mô hình nhanh hơn/nhỏ hơn: hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
Giảm bớt các bộ công cụ đang hoạt động: hermes chat -t "terminal"
Kiểm tra độ trễ mạng của bạn với nhà cung cấp
Đối với các model cục bộ, đảm bảo bạn có đủ GPU VRAM

Mức sử dụng token cao

Lý do: Cuộc trò chuyện dài, lời nhắc hệ thống dài dòng hoặc nhiều lệnh gọi công cụ tích lũy ngữ cảnh.

Giải pháp:

# Compress the conversation to reduce tokens
/compress

# Check session token usage
/usage

mẹo

Sử dụng /compress thường xuyên trong thời gian dài. Nó tóm tắt lịch sử hội thoại và giảm đáng kể việc sử dụng mã thông báo trong khi vẫn giữ nguyên ngữ cảnh.

Phiên quá dài

Lý do: Các cuộc hội thoại kéo dài sẽ tích lũy thông báo và kết quả đầu ra của công cụ, tiến gần đến giới hạn ngữ cảnh.

Giải pháp:

# Compress current session (preserves key context)
/compress

# Start a new session with a reference to the old one
hermes chat

# Resume a specific session later if needed
hermes chat --continue

Vấn đề về MCP

Máy chủ MCP không kết nối

Cause: Server binary not found, wrong command path, or missing runtime.

Solution:

# Ensure MCP dependencies are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

# For npm-based servers, ensure Node.js is available
node --version
npx --version

# Test the server manually
npx -y @modelcontextprotocol/server-filesystem /tmp

Verify your ~/.hermes/config.yaml MCP configuration:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

Tools not showing up from MCP server

Cause: Server started but tool discovery failed, tools were filtered out by config, or the server does not support the MCP capability you expected.

Solution:

Check gateway/agent logs for MCP connection errors
Ensure the server responds to the tools/list RPC method
Review any tools.include, tools.exclude, tools.resources, tools.prompts, or enabled settings under that server
Remember that resource/prompt utility tools are only registered when the session actually supports those capabilities
Use /reload-mcp after changing config

# Verify MCP servers are configured
hermes config show | grep -A 12 mcp_servers

# Restart Hermes or reload MCP after config changes
hermes chat

MCP timeout errors

Cause: The MCP server is taking too long to respond, or it crashed during execution.

Solution:

Increase the timeout in your MCP server config if supported
Check if the MCP server process is still running
For remote HTTP MCP servers, check network connectivity

cảnh báo

If an MCP server crashes mid-request, Hermes will report a timeout. Check the server's own logs (not just Hermes logs) to diagnose the root cause.

Profiles

How do profiles differ from just setting HERMES_HOME?

Profiles are a managed layer on top of HERMES_HOME. You could manually set HERMES_HOME=/some/path before every command, but profiles handle all the plumbing for you: creating the directory structure, generating shell aliases (hermes-work), tracking the active profile in ~/.hermes/active_profile, and syncing skill updates across all profiles automatically. They also integrate with tab completion so you don't have to remember paths.

No. Each messaging platform (Telegram, Discord, etc.) requires exclusive access to a bot token. If two profiles try to use the same token simultaneously, the second gateway will fail to connect. Create a separate bot per profile — for Telegram, talk to @BotFather to make additional bots.

No. Each profile has its own memory store, session database, and skills directory. They are completely isolated. If you want to start a new profile with existing memories and sessions, use hermes profile create newname --clone-all to copy everything from the current profile.

What happens when I run `hermes update`?

hermes update pulls the latest code and reinstalls dependencies once (not per-profile). It then syncs updated skills to all profiles automatically. You only need to run hermes update once — it covers every profile on the machine.

Can I move a profile to a different machine?

Yes. Export the profile to a portable archive and import it on the other machine:

# On the source machine
hermes profile export work ./work-backup.tar.gz

# Copy the file to the target machine, then:
hermes profile import ./work-backup.tar.gz work

The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup.

How many profiles can I run?

There is no hard limit. Each profile is just a directory under ~/.hermes/profiles/. The practical limit depends on your disk space and how many concurrent gateways your system can handle (each gateway is a lightweight Python process). Running dozens of profiles is fine; each idle profile uses no resources.

Workflows & Patterns

Using different models for different tasks (multi-model workflows)

Scenario: You use GPT-5.4 as your daily driver, but Gemini or Grok writes better social media content. Manually switching models every time is tedious.

Solution: Delegation config. Hermes can route subagents to a different model automatically. Set this in ~/.hermes/config.yaml:

delegation:
  model: "google/gemini-3-flash-preview"   # subagents use this model
  provider: "openrouter"                    # provider for subagents

Now when you tell Hermes "write me a Twitter thread about X" and it spawns a delegate_task subagent, that subagent runs on Gemini instead of your main model. Your primary conversation stays on GPT-5.4.

You can also be explicit in your prompt: "Delegate a task to write social media posts about our product launch. Use your subagent for the actual writing." The agent will use delegate_task, which automatically picks up the delegation config.

For one-off model switches without delegation, use /model in the CLI:

/model google/gemini-3-flash-preview    # switch for this session
# ... write your content ...
/model openai/gpt-5.4                   # switch back

See Subagent Delegation for more on how delegation works.

Running multiple agents on one WhatsApp number (per-chat binding)

Scenario: In OpenClaw, you had multiple independent agents bound to specific WhatsApp chats — one for a family shopping list group, another for your private chat. Can Hermes do this?

Current limitation: Hermes profiles each require their own WhatsApp number/session. You cannot bind multiple profiles to different chats on the same WhatsApp number — the WhatsApp bridge (Baileys) uses one authenticated session per number.

Workarounds:

Use a single profile with personality switching. Create different AGENTS.md context files or use the /personality command to change behavior per chat. The agent sees which chat it's in and can adapt.
Use cron jobs for specialized tasks. For a shopping list tracker, set up a cron job that monitors a specific chat and manages the list — no separate agent needed.
Use separate numbers. If you need truly independent agents, pair each profile with its own WhatsApp number. Virtual numbers from services like Google Voice work for this.
Use Telegram or Discord instead. These platforms support per-chat binding more naturally — each Telegram group or Discord channel gets its own session, and you can run multiple bot tokens (one per profile) on the same account.

See Profiles and WhatsApp setup for more details.

Controlling what shows up in Telegram (hiding logs and reasoning)

Scenario: You see gateway exec logs, Hermes reasoning, and tool call details in Telegram instead of just the final output.

Solution: The display.tool_progress setting in config.yaml controls how much tool activity is shown:

display:
  tool_progress: "off"   # options: off, new, all, verbose

off — Only the final response. No tool calls, no reasoning, no logs.
new — Shows new tool calls as they happen (brief one-liners).
all — Shows all tool activity including results.
verbose — Full detail including tool arguments and outputs.

For messaging platforms, off or new is usually what you want. After editing config.yaml, restart the gateway for changes to take effect.

You can also toggle this per-session with the /verbose command (if enabled):

display:
  tool_progress_command: true   # enables /verbose in the gateway

Managing skills on Telegram (slash command limit)

Scenario: Telegram has a 100 slash command limit, and your skills are pushing past it. You want to disable skills you don't need on Telegram, but hermes skills config settings don't seem to take effect.

Solution: Use hermes skills config to disable skills per-platform. This writes to config.yaml:

skills:
  disabled: []                    # globally disabled skills
  platform_disabled:
    telegram: [skill-a, skill-b]  # disabled only on telegram

After changing this, restart the gateway (hermes gateway restart or kill and relaunch). The Telegram bot command menu rebuilds on startup.

mẹo

Skills with very long descriptions are truncated to 40 characters in the Telegram menu to stay within payload size limits. If skills aren't appearing, it may be a total payload size issue rather than the 100 command count limit — disabling unused skills helps with both.

Shared thread sessions (multiple users, one conversation)

Scenario: You have a Telegram or Discord thread where multiple people mention the bot. You want all mentions in that thread to be part of one shared conversation, not separate per-user sessions.

Current behavior: Hermes creates sessions keyed by user ID on most platforms, so each person gets their own conversation context. This is by design for privacy and context isolation.

Workarounds:

Use Slack. Slack sessions are keyed by thread, not by user. Multiple users in the same thread share one conversation — exactly the behavior you're describing. This is the most natural fit.
Use a group chat with a single user. If one person is the designated "operator" who relays questions, the session stays unified. Others can read along.
Use a Discord channel. Discord sessions are keyed by channel, so all users in the same channel share context. Use a dedicated channel for the shared conversation.

Exporting Hermes to another machine

Scenario: You've built up skills, cron jobs, and memories on one machine and want to move everything to a new dedicated Linux box.

Solution:

Install Hermes Agent on the new machine:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Copy your entire ~/.hermes/ directory except the hermes-agent subdirectory (that's the code repo — the new install has its own):

# On the source machine
rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

Or use profile export/import:

# On source machine
hermes profile export default ./hermes-backup.tar.gz

# On target machine
hermes profile import ./hermes-backup.tar.gz default

On the new machine, run hermes setup to verify API keys and provider config are working. Re-authenticate any messaging platforms (especially WhatsApp, which uses QR pairing).

The ~/.hermes/ directory contains everything: config.yaml, .env, SOUL.md, memories/, skills/, state.db (sessions), cron/, and any custom plugins. The code itself lives in ~/.hermes/hermes-agent/ and is installed fresh.

Permission denied when reloading shell after install

Scenario: After running the Hermes installer, source ~/.zshrc gives a permission denied error.

Cause: This usually happens when ~/.zshrc (or ~/.bashrc) has incorrect file permissions, or when the installer couldn't write to it cleanly. It's not a Hermes-specific issue — it's a shell config permissions problem.

Solution:

# Check permissions
ls -la ~/.zshrc

# Fix if needed (should be -rw-r--r-- or 644)
chmod 644 ~/.zshrc

# Then reload
source ~/.zshrc

# Or just open a new terminal window — it picks up PATH changes automatically

If the installer added the PATH line but permissions are wrong, you can add it manually:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Error 400 on first agent run

Scenario: Setup completes fine, but the first chat attempt fails with HTTP 400.

Cause: Usually a model name mismatch — the configured model doesn't exist on your provider, or the API key doesn't have access to it.

Solution:

# Check what model and provider are configured
hermes config show | head -20

# Re-run model selection
hermes model

# Or test with a known-good model
hermes chat -q "hello" --model anthropic/claude-sonnet-4.6

If using OpenRouter, make sure your API key has credits. A 400 from OpenRouter often means the model requires a paid plan or the model ID has a typo.

Still Stuck?

If your issue isn't covered here:

Search existing issues: GitHub Issues
Ask the community: Nous Research Discord
File a bug report: Include your OS, Python version (python3 --version), Hermes version (hermes --version), and the full error message