Hermes Agent 配置指南从模型接入到多平台部署Hermes Agent 是 Nous Research 开源的 AI Agent 框架支持 CLI、桌面端、Web Dashboard 以及 20 消息平台Telegram、Discord、QQ、微信等。本文整理了日常使用中最常碰到的配置指令涵盖模型接入、图像生成、OAuth 登录、QQ/微信机器人部署等场景。目录1. 安装与快速开始2. 第三方模型配置3. Codex OAuth 登录4. 图像生成 (image_gen) 配置5. QQ 机器人配置6. 微信 (WeChat) 配置7. 其他消息平台8. 工具集 (Toolsets) 管理9. MCP 服务器接入10. 语音配置 (STT/TTS)11. 配置文件速查12. 常用运维指令1. 安装与快速开始# 一键安装自动配置 uv、Python、venv 和启动器curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash# 交互式聊天默认 CLI 模式hermes# 单次查询hermes chat-q什么是量子计算# 设置向导交互式引导配置模型、TTS、终端等hermes setup# 健康检查hermes doctor关键路径路径说明~/.hermes/config.yaml主配置文件只放设置不放密钥~/.hermes/.envAPI 密钥和秘密~/.hermes/skills/已安装的 skills~/.hermes/auth.jsonOAuth 令牌和凭证池~/.hermes/logs/网关和错误日志~/.hermes/state.db会话存储SQLite⚠️重要原则密钥放.env配置放config.yaml。永远不要在config.yaml里写 API key。2. 第三方模型配置Hermes 支持 35 模型提供商包括 OpenRouter、Anthropic、OpenAI、Google、DeepSeek、xAI、小米等。2.1 交互式选择模型# 打开模型选择器推荐新手使用hermes model# 或通过设置向导hermes setup model2.2 手动配置模型# 设置默认模型和提供商hermes configsetmodel.default deepseek-chat hermes configsetmodel.provider deepseek# 设置自定义 base_url用于私有部署或兼容 APIhermes configsetmodel.base_url https://your-api.com/v1# 设置 API Key密钥放 .env不要放 config.yamlechoDEEPSEEK_API_KEYsk-xxxxxxxx~/.hermes/.env2.3 常用提供商一览提供商环境变量说明OpenRouterOPENROUTER_API_KEY聚合 200 模型AnthropicANTHROPIC_API_KEYClaude 系列Google GeminiGOOGLE_API_KEYGemini 系列DeepSeekDEEPSEEK_API_KEYDeepSeek V3/R1xAIXAI_API_KEYGrok 系列小米XIAOMI_API_KEYMiMo 系列通义千问DASHSCOPE_API_KEYQwen 系列智谱 GLMGLM_API_KEYGLM/CogViewHuggingFaceHF_TOKEN开源模型推理Ollama本地无需 Key需设置base_url2.4 模型别名在config.yaml中定义快捷别名之后用/model fav即可切换model:aliases:fav:openrouter/anthropic/claude-sonnet-4.6deep:deepseek/deepseek-chatqwen:dashscope/qwen-maxCLI 方式添加hermes configsetmodel.aliases.fav openrouter/anthropic/claude-sonnet-4.6内置别名sonnet、opus、gpt、gemini、deepseek、grok、qwen、mimo等。2.5 Fallback 链主模型不可用时自动切换到备用模型hermes fallbackaddanthropic/claude-sonnet-4.6 hermes fallbackaddopenrouter/deepseek/deepseek-chat hermes fallback list# 查看当前链hermes fallback remove# 移除2.6 凭证池多 Key 轮换同一提供商可以配置多个 API Key系统自动轮换、跳过耗尽的 Keyhermes auth# 交互式凭证管理器hermes authadd# 添加凭证hermes auth list# 查看所有凭证hermes auth status# 查看凭证状态3. Codex OAuth 登录openai-codex提供商使用 OAuth 设备码流程登录不需要 API Key。登录后可用于聊天模型和图像生成。3.1 登录流程# 触发 Codex OAuth 登录hermes authaddopenai-codex系统会显示一个设备码和 URL在浏览器中打开 URL 并输入设备码完成授权。登录成功后令牌自动保存到~/.hermes/auth.json。3.2 设为默认模型hermes configsetmodel.provider openai-codex hermes configsetmodel.default gpt-5# Codex 支持的模型名3.3 Nous Portal 登录Nous Portal 提供订阅制的工具网关图像生成、网页搜索等hermes authaddnous# 或使用 Portal 快速设置hermes portal3.4 常见问题Codex OAuth 轮询失败SSL / 代理问题如果你在代理环境下遇到SSL handshake failed需要确保代理使用 CONNECT 隧道而非 MITM# 检查代理配置echo$HTTPS_PROXY# 临时绕过代理unsetHTTPS_PROXY hermes authaddopenai-codex4. 图像生成 (ImageGen) 配置Hermes 内置图像生成工具支持多个后端提供商。4.1 可用提供商提供商认证方式可用模型openai-codexCodex OAuthGPT-Image-2 (Low/Medium/High)openaiOPENAI_API_KEYGPT-Image-1falFAL_KEY所有 fal-ai/* 模型nous(网关)Nous 订阅所有 FAL 托管模型xaiXAI OAuth / API KeyGrok ImaginekreaKREA_API_KEYKrea 2deepinfraDEEPINFRA_API_KEY多模型4.2 交互式配置# 打开工具配置界面选择 image_gen → 选择提供商 → 选择模型hermes tools# 如果已经配置过但想重新选择需要先禁用再启用hermes tools disable image_gen hermes toolsenableimage_gen4.3 手动配置# 使用 Codex OAuth不需要额外 API Keyhermes configsetimage_gen.provider openai-codex hermes configsetimage_gen.model gpt-image-2-medium hermes configsetimage_gen.use_gatewayfalse# 使用 FAL 直连hermes configsetimage_gen.provider fal hermes configsetimage_gen.model fal-ai/fast-sdxlechoFAL_KEYyour-fal-key~/.hermes/.env# 使用 Nous 订阅网关FAL 托管通过 Nous 计费hermes configsetimage_gen.provider nous hermes configsetimage_gen.model fal-ai/gpt-image-2 hermes configsetimage_gen.use_gatewaytrue4.4 FAL 托管的 GPT Image 模型模型速度特点价格fal-ai/gpt-image-1.5~15s提示词遵循度高$0.034/张fal-ai/gpt-image-2~20sSOTA 文字渲染、中文支持、照片级真实感$0.04–0.06/张4.5 调试exportIMAGE_TOOLS_DEBUGtrue# 日志保存到 ./logs/image_tools_debug_session_id.json4.6 验证当前配置hermes config get image_gen# 输出示例# use_gateway: false# provider: openai-codex# model: gpt-image-2-medium5. QQ 机器人配置Hermes 通过 QQ 官方 Bot APIv2 连接 QQ 平台支持私聊、群聊、语音转文字等。5.1 前置准备前往 QQ 开放平台 创建机器人应用获取AppID和ClientSecret在机器人管理后台开启所需的权限消息内容意图等5.2 配置方式方式一环境变量echoQQ_APP_IDyour-app-id~/.hermes/.envechoQQ_CLIENT_SECRETyour-secret~/.hermes/.env方式二config.yamlchannels:qqbot:enabled:trueextra:app_id:your-app-idclient_secret:your-secretmarkdown_support:true# 启用 QQ Markdownmsg_type 2dm_policy:pairing# 私聊策略open | allowlist | disabled | pairingallow_from:[openid_1]# 私聊白名单group_policy:pairing# 群聊策略group_allow_from:[group_openid_1]# 群聊白名单方式三扫码配置推荐Hermes 支持扫码一键配置 QQ 机器人hermes gateway setup# 选择 QQ Bot → 扫码 → 自动完成配置5.3 启动网关# 启动所有已配置的消息平台hermes gateway run# 安装为系统服务开机自启hermes gatewayinstallhermes gateway start# 查看状态hermes gateway status# 查看日志hermes logs-f5.4 QQ 语音转文字QQ 机器人支持三级语音转写优先级QQ 内置 ASR腾讯免费自动优先配置的 STT 提供商config.yaml 中的stt配置跳过不转写channels:qqbot:extra:stt:provider:zai# zai (GLM-ASR), openai (Whisper)baseUrl:https://open.bigmodel.cn/api/coding/paas/v4apiKey:your-keymodel:glm-asr5.5 QQ 平台工具集配置可以为 QQ 平台单独配置可用的工具集hermes tools# 交互式界面中选择 qqbot 平台勾选/取消工具在config.yaml中也可以直接指定toolsets:qqbot:-terminal-file-web-image_gen-vision-memory-skills-tts6. 微信 (WeChat) 配置Hermes 通过腾讯 iLink Bot API 连接微信个人账号。6.1 配置流程# 启动网关设置向导选择 WeChathermes gateway setup# 选择 WeChat → 扫码登录 → 自动完成配置6.2 手动配置channels:weixin:enabled:trueextra:# iLink Bot Token扫码后自动获取token:your-ilink-token6.3 查看微信连接状态hermes status|grep-iweixin# 输出示例Weixin:o9cq80_HJ1gUXEHrFE6JmJfV4mk4im.wechat6.4 注意事项微信通过 iLink 长轮询接收消息需要保持网关进程运行出站消息必须回传最新的context_tokenHermes 自动处理媒体文件通过 AES-128-ECB 加密 CDN 协议传输iLink 有 30 秒速率限制批量操作时需注意间隔7. 其他消息平台Hermes 支持 20 消息平台配置方式大同小异7.1 Telegram# 1. 通过 BotFather 创建 Bot获取 Token# 2. 配置echoTELEGRAM_BOT_TOKENyour-token~/.hermes/.env hermes gateway setup# 选择 Telegram7.2 Discord# 1. 在 Discord Developer Portal 创建 Bot# 2. 开启 Message Content Intent必须echoDISCORD_BOT_TOKENyour-token~/.hermes/.env hermes gateway setup# 选择 Discord7.3 SlackechoSLACK_BOT_TOKENxoxb-xxx~/.hermes/.envechoSLACK_APP_TOKENxapp-xxx~/.hermes/.env# 需要订阅 message.channels 事件才能在公开频道响应7.4 钉钉/飞书/企业微信hermes gateway setup# 选择对应平台按向导操作7.5 平台总览平台协议备注TelegramBot API最成熟DiscordBot API需开启 Message Content IntentSlackSocket Mode需订阅 message.channelsQQ官方 Bot API v2支持扫码配置微信iLink Bot API扫码登录WhatsAppBaileys / Business Cloud API两种模式Signalsignal-cli需要额外安装TeamsMicrosoft Graph企业版钉钉企业内部应用Webhook飞书企业自建应用WebhookMatrixMatrix Client-SDK开源协议EmailIMAP/SMTP邮件集成8. 工具集 (Toolsets) 管理8.1 交互式管理hermes tools# 打开交互式工具配置界面curses UI8.2 命令行管理hermes tools list# 查看所有工具及状态hermes toolsenableimage_gen# 启用图像生成hermes tools disable computer_use# 禁用桌面控制hermes toolsenablebrowser--force# 强制启用8.3 常用工具集工具集功能web网页搜索 内容提取browser浏览器自动化terminalShell 命令执行file文件读写/搜索/补丁image_gen图像生成video_gen视频生成vision图像分析tts文字转语音computer_use桌面 GUI 控制memory跨会话记忆delegation子 Agent 任务委派cronjob定时任务管理skillsSkill 管理⚠️ 工具变更在/reset新会话后生效不会在当前对话中生效保护 prompt cache。8.4 为特定平台配置工具集hermes tools# 在交互式界面中选择平台cli/telegram/qqbot/discord...为每个平台独立配置工具9. MCP 服务器接入Hermes 内置 MCP 客户端可以连接任何 MCP 服务器并将其工具作为一等公民使用。9.1 安装 MCP SDKpipinstallmcp9.2 配置 MCP 服务器在~/.hermes/config.yaml中添加mcp_servers:# stdio 传输本地命令filesystem:command:npxargs:[-y,modelcontextprotocol/server-filesystem,/home/user/documents]timeout:30github:command:npxargs:[-y,modelcontextprotocol/server-github]env:GITHUB_PERSONAL_ACCESS_TOKEN:ghp_xxxxxxxxxxxx# HTTP 传输远程服务器company_api:url:https://mcp.mycompany.com/v1/mcpheaders:Authorization:Bearer sk-xxxxxxxxtimeout:1809.3 管理 MCP 服务器hermes mcp list# 列出已配置的 MCP 服务器hermes mcpaddNAME--urlURL# 添加 HTTP 服务器hermes mcpaddNAME--commandnpx ...# 添加 stdio 服务器hermes mcptestNAME# 测试连接hermes mcp remove NAME# 移除hermes mcp catalog# 浏览官方目录hermes mcpinstallNAME# 从目录安装工具命名规则mcp_{server_name}_{tool_name}例如mcp_github_list_issues。10. 语音配置 (STT/TTS)10.1 STT语音转文字stt:enabled:trueprovider:local# local | groq | openai | mistral | elevenlabs | deepinfralocal:model:base# tiny, base, small, medium, large-v3自动检测优先级local faster-whisper → Groq → OpenAI → Mistral。# 安装本地 Whisper免费pipinstallfaster-whisper10.2 TTS文字转语音tts:provider:edge# edge | elevenlabs | openai | minimax | mistral | gemini | piper | kittentts提供商环境变量免费Edge TTS默认无需✅ 免费ElevenLabsELEVENLABS_API_KEY免费额度OpenAIVOICE_TOOLS_OPENAI_KEY付费MiniMaxMINIMAX_API_KEY付费GeminiGOOGLE_API_KEY免费额度Piper / KittenTTS无需✅ 本地免费10.3 语音聊天模式在聊天中使用斜杠命令/voice on # 语音对话模式语音输入 语音回复 /voice tts # 始终语音回复 /voice off # 关闭语音11. 配置文件速查11.1 config.yaml 常用配置段# 模型配置model:default:deepseek-chatprovider:deepseekbase_url:https://api.deepseek.com/v1# 自定义端点# Agent 行为agent:max_turns:90# 最大工具调用轮次tool_use_enforcement:auto# 工具使用策略reasoning_effort:medium# 推理深度# 终端terminal:backend:local# local | docker | sshtimeout:180# 命令超时秒# 显示display:skin:default# 主题皮肤interface:cli# cli | tuilanguage:zh# 界面语言show_cost:true# 显示费用# 安全approvals:mode:smart# smart | manual | off# 记忆memory:memory_enabled:trueuser_profile_enabled:true# 压缩长对话自动压缩compression:enabled:truethreshold:0.50# 上下文使用率触发压缩target_ratio:0.20# 压缩目标比率# 子 Agent 委派delegation:max_concurrent_children:3max_iterations:50max_spawn_depth:1# 定时任务# 通过 hermes cron 或 cronjob 工具管理不在 config.yaml 中配置11.2 完整配置参考hermes config show# 查看当前完整配置hermes config edit# 用编辑器打开配置文件hermes config get section# 查看某个配置段hermes configsetKEY VAL# 设置配置项hermes configunsetKEY# 删除配置项hermes config check# 检查缺失的配置段hermes config path# 显示配置文件路径hermes config env-path# 显示 .env 文件路径12. 常用运维指令12.1 会话管理hermes sessions list# 列出所有会话hermes sessions browse# 浏览会话hermes sessionsrenameID NAME# 重命名会话hermes sessionsexportOUT# 导出会话hermes sessions stats# 统计信息hermes--continue# 恢复最近的会话hermes--resumeSESSION_ID# 恢复指定会话12.2 定时任务hermescronlist# 列出定时任务hermescroncreate0 9 * * *# 创建每天 9:00hermescronpause ID# 暂停hermescronresume ID# 恢复hermescronrun ID# 立即执行一次hermescronremove ID# 删除12.3 网关管理hermes gateway run# 前台运行网关hermes gatewayinstall# 安装为 systemd 服务hermes gateway start# 启动服务hermes gateway stop# 停止服务hermes gateway restart# 重启hermes gateway status# 查看状态hermes gateway setup# 设置向导添加新平台12.4 Profile多配置隔离hermes profile list# 列出所有 profilehermes profile create work# 创建新 profilehermes profile use work# 切换到 work profilehermes profile delete work# 删除每个 Profile 独立拥有 skills、plugins、cron、memories 和 config。12.5 日志与调试hermes logs# 查看日志hermes logs-f# 实时跟踪hermes logs errors# 只看错误日志hermes doctor# 全面健康检查hermes doctor--fix# 自动修复hermes status# 组件状态hermes status--all# 详细状态12.6 其他实用工具# 桌面应用hermes desktop# 启动原生桌面应用Electron# Web 管理面板hermes dashboard# 启动 Web Dashboard# 本地 OpenAI 兼容代理hermes proxy# 将 OAuth 提供商暴露为 OpenAI API# Skills 管理hermes skills list# 列出已安装的 Skillshermes skills browse# 浏览 Skill 目录hermes skillsinstallNAME# 安装 Skill# 主题切换hermes skin list# 列出可用皮肤hermes skin use synthwave# 切换皮肤# 更新hermes update# 更新到最新版本附录环境变量速查变量用途OPENROUTER_API_KEYOpenRouter 聚合平台ANTHROPIC_API_KEYClaude 模型OPENAI_API_KEYOpenAI 模型GOOGLE_API_KEYGemini 模型DEEPSEEK_API_KEYDeepSeek 模型XAI_API_KEYxAI Grok 模型XIAOMI_API_KEY小米 MiMo 模型DASHSCOPE_API_KEY通义千问GLM_API_KEY智谱 GLMHF_TOKENHuggingFaceFAL_KEYFAL.ai 图像/视频KREA_API_KEYKrea 图像TELEGRAM_BOT_TOKENTelegram BotDISCORD_BOT_TOKENDiscord BotSLACK_BOT_TOKENSlack BotQQ_APP_IDQQ 机器人 App IDQQ_CLIENT_SECRETQQ 机器人密钥ELEVENLABS_API_KEYElevenLabs TTSVOICE_TOOLS_OPENAI_KEYOpenAI 语音GROQ_API_KEYGroqSTT/模型FIRECRAWL_API_KEYFirecrawl 网页抓取更多信息官方文档https://hermes-agent.nousresearch.com/docs/GitHubhttps://github.com/NousResearch/hermes-agent在终端中运行hermes --help查看所有命令运行hermes setup启动交互式设置向导