Fichier de configuration Hermes Agent

Après l'installation, toute la configuration et les données sont stockées dans~/.hermes/Ci-dessous :

~/.hermes/
├── config.yaml      # 主配置文件（模型、工具、终端后端等）
├── .env             # API 密钥和 Secret（不提交到版本库）
├── auth.json        # OAuth 凭据（Nous Portal 等）
├── SOUL.md          # Agent 人格设定文件
├── memories/        # 持久记忆（MEMORY.md、USER.md）
├── skills/          # 技能文件（Agent 自动创建和管理）
├── cron/            # 定时任务配置
├── sessions/        # 网关会话记录
└── logs/            # 日志（API 密钥自动脱敏）

Principes importants：

• Secrets (clés API, jetons, mots de passe)→ Stocker.env
• Configuration générale (modèles, outils, backends de terminal, etc.)→ Stockerconfig.yaml
• Utilisationhermes config set KEY VALUELes commandes sont automatiquement acheminées vers le bon fichier

Sélectionner le fournisseur de modèle

Exécutez la commande suivante pour accéder à la sélection interactive :

hermes model

Chemin recommandé : Nous Portal (le plus simple)

Un seul abonnement couvre 300+ modèles + Tool Gateway (recherche web, génération d'images, TTS, navigateur cloud), pas besoin de demander plusieurs clés API séparément :

hermes setup

Après l'exécution, connectez-vous via OAuth, et la configuration du fournisseur ainsi que l'activation de Tool Gateway sont effectuées automatiquement.

Aperçu des fournisseurs courants

Exigences de la fenêtre de contexte du modèle: Hermes exige que le modèle prenne en charge au moins64,000 tokensde contexte. Lors de l'utilisation de modèles locaux, assurez-vous qu'une taille de contexte suffisante est définie dans les paramètres de démarrage (par ex.--ctx-size 65536）。

Changer de fournisseur

Vous pouvez changer à tout moment sans modifier de code :

hermes model

Trois modes de configuration

Premier lancementhermes setupÀ ce moment-là, il vous sera demandé de sélectionner un mode d'initialisation :

Mode 1 : Configuration rapide (Nous Portal)

Connexion OAuth gratuite, configure automatiquement les modèles + Tool Gateway (recherche web, génération d'images, TTS, navigateur).Recommandé pour les nouveaux utilisateurs.

Mode 2 : Configuration complète

Configurer manuellement les fournisseurs, les ensembles d’outils, les plateformes de messagerie, etc. un par un. Convient aux utilisateurs ayant des exigences claires et leurs propres clés API.

Mode 3 : Table rase (Point de départ vierge)

Ne conservez que l’ensemble d’exécution minimal (fournisseurs, outils de fichiers, outils de terminal), tout le reste est désactivé. Convient aux utilisateurs avancés qui ont besoin d’un contrôle précis des limites des capacités de l’Agent. Le mode vierge écrit explicitement la configuration pour empêcherhermes updatel’activation automatique de nouvelles fonctionnalités par la suite.

Démarrer la première conversation

Une fois la configuration terminée, démarrez Hermes :

hermes          # 经典 CLI 模式
hermes --tui    # 现代 TUI 模式（推荐，支持鼠标、弹窗等）

Après le démarrage, une bannière d’accueil s’affichera, montrant le modèle actuel, les outils disponibles et les compétences chargées.

Vérifiez que tout fonctionne normalement

Testez avec une invite simple mais spécifique :

Check my current directory, tell me what files are in it, and identify the main project entry file.

Indicateur de réussite：

• La bannière affiche correctement le modèle/fournisseur que vous avez sélectionné
• L'Agent répond normalement sans aucun message d'erreur
• Peut appeler des outils si nécessaire (terminal, lecture de fichiers, etc.)
• Les conversations peuvent se poursuivre sur plus d'un tour

Vérifier la récupération de session

Confirmer que la continuité entre sessions fonctionne correctement :

Check my current directory, tell me what files are in it, and identify the main project entry file.

Opérations de base de l'interface TUI

Exécutezhermes --tuiAprès être entré en mode TUI moderne, opérations courantes :

Commandes slash principales

Configuration du backend d'exécution du terminal

Hermes prend en charge six environnements d'exécution de terminal, déterminant où s'exécutent les commandes Shell de l'Agent :

Passer au backend Docker (recommandé pour la production)

hermes config set terminal.backend docker

Ou modifiez directement~/.hermes/config.yaml：

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

Instructions de sécurité: Par défautlocalLe backend donne à l'Agent les mêmes permissions de système de fichiers que vous. Si vous souhaitez limiter le champ d'action de l'Agent, passez àdockerLe backend est la méthode la plus simple et la plus efficace.

Gestion des ensembles d'outils

Hermes regroupe 70+ outils intégrés en 28 ensembles d'outils, qui peuvent être activés ou désactivés selon les besoins:

hermes tools    # 打开可视化工具集管理界面（curses UI）

Principaux ensembles d’outils

Désactiver un ensemble d'outils spécifique: Cet ensemble d'outils disparaît complètement de l'invite système, pas seulement désactivé — cela économise des tokens et empêche l'Agent d'utiliser à mauvais escient des outils qu'il ne devrait pas utiliser.

Commandes courantes de gestion de la configuration

# 查看当前完整配置
hermes config

# 用编辑器打开 config.yaml
hermes config edit

# 设置单个配置值（自动路由到正确文件）
hermes config set model anthropic/claude-sonnet-4-6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # 自动存入 .env

# 检查是否有新版本引入的配置项未填写
hermes config check

# 交互式补全缺失配置
hermes config migrate

# 诊断所有配置问题
hermes doctor

# 更新到最新版本
hermes update

Dépannage courant

Question 1 :hermes: command not found

# 刷新 Shell 配置
source ~/.bashrc   # ou  source ~/.zshrc

# 如果仍然找不到，检查 PATH
echo $PATH
# 确保 ~/.local/bin 在其中
export PATH="$HOME/.local/bin:$PATH"

Question 2 :API key not set/ Modèle ne répond pas

# 重新配置提供商
hermes model

# 或直接设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

Problème 3 : Réponses vides ou illisibles

Cela peut être dû à une authentification incorrecte du fournisseur ou à une sélection de modèle incorrecte :

# 重新选择模型
hermes model

# 全面诊断
hermes doctor

Problème 4 : Erreur de fenêtre de contexte insuffisante

Hermes exige que le modèle prenne en charge un contexte d'au moins 64K Token. Passez à un modèle avec un contexte plus large, ou augmentez le paramètre de contexte lors de l'utilisation de modèles locaux (par exemple, Ollama :OLLAMA_NUM_CTX=65536）。

Question 5 :hermes --continueImpossible de trouver les anciennes conversations

# 查看所有会话
hermes sessions list

# 确认当前 Profile
hermes profile list

Kit de récupération universel

Si vous rencontrez des problèmes étranges, suivez les étapes ci-dessous dans l'ordre :

hermes doctor           # 1. 诊断
hermes model            # 2. 检查模型配置
hermes setup            # 3. 重新向导配置
hermes sessions list    # 4. 查看会话状态
hermes --continue       # 5. 尝试恢复会话
hermes gateway status   # 6. 检查网关状态（如已启用）

Aperçu de la configuration avancée

Après avoir terminé l'installation de base, les fonctionnalités suivantes peuvent être activées selon les besoins (détaillées dans les chapitres suivants) :

Se connecter à une plateforme de messagerie

hermes gateway setup    # 交互式配置 Telegram、Discord、Slack 等
hermes gateway          # 启动消息网关

Activer le mode vocal

# 安装语音依赖
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

# 在 CLI 中启用
/voice on
# 按 Ctrl+B 开始录音

Connecter des serveurs MCP

Dans~/.hermes/config.yamlAjouter dans :

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

hermes mcp    # 交互式管理 MCP 服务器

Intégration de l'éditeur (ACP)

hermes acp    # 启动编辑器 Agent 模式（VS Code / Zed / JetBrains）

Référence rapide des commandes