1. 为什么我建议你用统一 Key 跑 Hermes AgentHermes Agent 是一个可自托管、带长期记忆和技能沉淀能力的轻量 AI Agent支持 TUI 终端交互也能通过消息网关接入 QQ、飞书、钉钉等平台。它适合想在自己服务器上养一个「越用越懂你」的助手的人也适合想把 Agent 接进日常消息流、随手就能调用的开发者。但真正动手部署时很多人会卡在同一个地方模型通道。Hermes 支持 Qwen、GLM、Kimi、Claude、Gemini 以及各种 OpenAI 兼容接口听起来很自由实际配置时你要为每个模型单独申请 Key、记不同的 Base URL、处理不同的鉴权格式。一旦想换模型或者加一个备用通道就得回去翻控制台、改配置、重启服务来回折腾。我试过用 TaoToken 把这件事收敛掉一个统一 Key、一个 API 通道Hermes 的 config.toml 里只写一份 provider 配置后面换模型只改模型名不动鉴权。这篇就按「从零部署到跑通第一个 AI 助手」的路径走一遍覆盖 TUI 交互和消息网关接入两个场景配置骨架可以直接复制。2. 部署前把 TaoToken 通道准备好TaoToken 在这里扮演的是「统一模型入口」的角色。你不需要在 Hermes 里为每个模型厂商写一套 provider而是把 TaoToken 的 API 地址和 Key 填一次Hermes 通过 OpenAI 兼容协议去请求模型名按需切换。先拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台在 API Keys 页面创建一个新 Key。创建时建议按用途命名比如hermes-agent方便以后区分是哪个服务在用。创建完复制保存这个 Key 只在创建时完整显示一次。如果你还没想好模型选哪个可以先在「模型对话」页面试几个确认响应速度和效果再写进配置。模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteAPI 基础地址统一用https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例配置前扫一眼能少踩很多格式坑。注意Key 不要写进会提交到 Git 的文件里。Hermes 的 config.toml 如果放在仓库中用环境变量引用或者把配置文件加进 .gitignore。3. 可复制的 config.toml 骨架Hermes 的配置核心是config.toml默认位置在~/.config/hermes/config.toml部分安装方式在~/.hermes/config.toml以hermes setup提示为准。下面这份骨架把 TaoToken 作为主 provider你可以直接复制后改模型名。# ~/.config/hermes/config.toml [agent] name my-hermes language zh-CN memory_enabled true [provider.taotoken] type openai base_url https://taotoken.net/api api_key env:TAOTOKEN_API_KEY default_model glm-4.5-air [provider.taotoken.models] chat glm-4.5-air reasoning claude-sonnet-4 fast glm-4.5-air [tui] theme default show_token_usage true [gateway] enabled false platform qq几个关键点说明。type openai表示走 OpenAI 兼容协议TaoToken 的/api路径兼容这套格式。api_key用env:前缀引用环境变量避免明文写在文件里。default_model和[provider.taotoken.models]里的模型名按你实际要用的填TaoToken 支持的模型列表在控制台或文档里能查到。环境变量这样设置写进~/.bashrc或~/.zshrcexport TAOTOKEN_API_KEYsk-你的Key然后source ~/.bashrc生效。如果你更习惯用hermes setup的交互式配置在「选择模型提供商」那一步选 OpenAI 兼容 / CustomBase URL 填https://taotoken.net/apiAPI Key 粘贴你的 Key模型名手动输入即可。交互式配置和手写 config.toml 效果一样手写的好处是改起来快、能版本管理。4. 启动并验证 TUI 响应配置写好后先别急着接消息网关在 TUI 里把链路跑通。执行hermes如果提示命令不存在先source ~/.bashrc刷新环境变量或者用hermes setup重新走一遍安装引导。进入 TUI 后界面底部会有输入框直接打字提问比如「用一句话介绍你自己」。正常响应会流式输出同时show_token_usage true会在状态栏显示本次消耗的 token 数。如果看到回复内容但 token 显示为 0说明用量统计没接上检查 provider 配置里type是否为openai。想验证模型切换是否生效在 TUI 里用斜杠命令/model claude-sonnet-4再问一个问题对比响应风格。如果报模型不存在说明[provider.taotoken.models]里没写这个模型名或者 TaoToken 那边该模型未开通。回到控制台确认模型可用性再改配置。TUI 阶段还有一个容易忽略的点长期记忆。memory_enabled true时Hermes 会把对话中的关键信息存到本地跨会话保留。你可以退出再进来问「我刚才让你介绍自己时说了什么」能答上来就说明记忆生效了。记忆文件默认在~/.hermes/memory/下备份或迁移时记得带上。5. 接入消息网关并验证回传TUI 跑通后接消息网关。以 QQ Bot 为例执行hermes gateway setup按引导选择平台、扫码创建机器人、设置运行方式。建议选「作为系统服务运行」这样服务器重启后网关会自动拉起。运行用户填root或你的实际用户取决于 Hermes 安装位置和权限。配置完成后启动网关hermes gateway restart验证回传是否正常用手机 QQ 给机器人发一条消息比如「现在几点」。如果几秒内收到回复说明网关链路通了。没收到的话按顺序排查hermes gateway status看服务是否在跑journalctl -u hermes-gateway -n 50看日志有没有鉴权错误或连接超时确认 config.toml 里[gateway]段的enabled是true。网关场景下模型调用走的还是同一份 TaoToken 配置所以 TUI 能通、网关一般也能通。如果网关报模型错误但 TUI 正常多半是网关服务启动时没读到环境变量。系统服务不会自动继承你 shell 里的TAOTOKEN_API_KEY需要在 service 文件里加Environment或者在 config.toml 里临时用明文 Key 验证一下确认是环境变量问题后再改回安全方式。6. 本篇常见错排查报 401 或 invalid api keyKey 复制时带了空格或者环境变量没生效。echo $TAOTOKEN_API_KEY确认输出注意前后不要有换行。如果 Key 是在 TaoToken 控制台刚创建的确认没有误删。报 model not foundconfig.toml 里的模型名和 TaoToken 实际支持的名称不一致。模型名区分大小写去控制台或文档核对。default_model和[provider.taotoken.models]里的名字要能对上。TUI 能回复但网关不回先看hermes gateway status服务没跑就hermes gateway restart。服务在跑但不回看日志里有没有connection refused或timeout通常是服务器出站网络或防火墙问题确认能访问https://taotoken.net/api。hermes 命令找不到安装脚本写入了 shell 配置但当前会话没加载。source ~/.bashrc或source ~/.zshrc或者直接开一个新终端。记忆不生效检查memory_enabled是否为true以及~/.hermes/memory/目录是否有写权限。用 root 跑过之后再用普通用户跑可能因为目录属主问题写不进去。想换模型但不想改配置TUI 里用/model命令临时切换重启后回到default_model。要永久换改 config.toml 里的default_model然后重启 Hermes。如果你打算长期跑编码类任务或者接 Agent 工作流可以看下 Coding Plan额度模型和按量计费不太一样适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteKey 管理和用量查看都在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite需要新建或轮换 Key 时走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite配置过程中如果卡在某个报错先回接入文档对照请求格式大部分问题出在 base_url 多写了斜杠或者模型名拼错https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Hermes Agent 部署全指南：用 TaoToken 统一 Key 搭建你的第一个 AI 助手
1. 为什么我建议你用统一 Key 跑 Hermes AgentHermes Agent 是一个可自托管、带长期记忆和技能沉淀能力的轻量 AI Agent支持 TUI 终端交互也能通过消息网关接入 QQ、飞书、钉钉等平台。它适合想在自己服务器上养一个「越用越懂你」的助手的人也适合想把 Agent 接进日常消息流、随手就能调用的开发者。但真正动手部署时很多人会卡在同一个地方模型通道。Hermes 支持 Qwen、GLM、Kimi、Claude、Gemini 以及各种 OpenAI 兼容接口听起来很自由实际配置时你要为每个模型单独申请 Key、记不同的 Base URL、处理不同的鉴权格式。一旦想换模型或者加一个备用通道就得回去翻控制台、改配置、重启服务来回折腾。我试过用 TaoToken 把这件事收敛掉一个统一 Key、一个 API 通道Hermes 的 config.toml 里只写一份 provider 配置后面换模型只改模型名不动鉴权。这篇就按「从零部署到跑通第一个 AI 助手」的路径走一遍覆盖 TUI 交互和消息网关接入两个场景配置骨架可以直接复制。2. 部署前把 TaoToken 通道准备好TaoToken 在这里扮演的是「统一模型入口」的角色。你不需要在 Hermes 里为每个模型厂商写一套 provider而是把 TaoToken 的 API 地址和 Key 填一次Hermes 通过 OpenAI 兼容协议去请求模型名按需切换。先拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台在 API Keys 页面创建一个新 Key。创建时建议按用途命名比如hermes-agent方便以后区分是哪个服务在用。创建完复制保存这个 Key 只在创建时完整显示一次。如果你还没想好模型选哪个可以先在「模型对话」页面试几个确认响应速度和效果再写进配置。模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteAPI 基础地址统一用https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容的 base_url 使用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例配置前扫一眼能少踩很多格式坑。注意Key 不要写进会提交到 Git 的文件里。Hermes 的 config.toml 如果放在仓库中用环境变量引用或者把配置文件加进 .gitignore。3. 可复制的 config.toml 骨架Hermes 的配置核心是config.toml默认位置在~/.config/hermes/config.toml部分安装方式在~/.hermes/config.toml以hermes setup提示为准。下面这份骨架把 TaoToken 作为主 provider你可以直接复制后改模型名。# ~/.config/hermes/config.toml [agent] name my-hermes language zh-CN memory_enabled true [provider.taotoken] type openai base_url https://taotoken.net/api api_key env:TAOTOKEN_API_KEY default_model glm-4.5-air [provider.taotoken.models] chat glm-4.5-air reasoning claude-sonnet-4 fast glm-4.5-air [tui] theme default show_token_usage true [gateway] enabled false platform qq几个关键点说明。type openai表示走 OpenAI 兼容协议TaoToken 的/api路径兼容这套格式。api_key用env:前缀引用环境变量避免明文写在文件里。default_model和[provider.taotoken.models]里的模型名按你实际要用的填TaoToken 支持的模型列表在控制台或文档里能查到。环境变量这样设置写进~/.bashrc或~/.zshrcexport TAOTOKEN_API_KEYsk-你的Key然后source ~/.bashrc生效。如果你更习惯用hermes setup的交互式配置在「选择模型提供商」那一步选 OpenAI 兼容 / CustomBase URL 填https://taotoken.net/apiAPI Key 粘贴你的 Key模型名手动输入即可。交互式配置和手写 config.toml 效果一样手写的好处是改起来快、能版本管理。4. 启动并验证 TUI 响应配置写好后先别急着接消息网关在 TUI 里把链路跑通。执行hermes如果提示命令不存在先source ~/.bashrc刷新环境变量或者用hermes setup重新走一遍安装引导。进入 TUI 后界面底部会有输入框直接打字提问比如「用一句话介绍你自己」。正常响应会流式输出同时show_token_usage true会在状态栏显示本次消耗的 token 数。如果看到回复内容但 token 显示为 0说明用量统计没接上检查 provider 配置里type是否为openai。想验证模型切换是否生效在 TUI 里用斜杠命令/model claude-sonnet-4再问一个问题对比响应风格。如果报模型不存在说明[provider.taotoken.models]里没写这个模型名或者 TaoToken 那边该模型未开通。回到控制台确认模型可用性再改配置。TUI 阶段还有一个容易忽略的点长期记忆。memory_enabled true时Hermes 会把对话中的关键信息存到本地跨会话保留。你可以退出再进来问「我刚才让你介绍自己时说了什么」能答上来就说明记忆生效了。记忆文件默认在~/.hermes/memory/下备份或迁移时记得带上。5. 接入消息网关并验证回传TUI 跑通后接消息网关。以 QQ Bot 为例执行hermes gateway setup按引导选择平台、扫码创建机器人、设置运行方式。建议选「作为系统服务运行」这样服务器重启后网关会自动拉起。运行用户填root或你的实际用户取决于 Hermes 安装位置和权限。配置完成后启动网关hermes gateway restart验证回传是否正常用手机 QQ 给机器人发一条消息比如「现在几点」。如果几秒内收到回复说明网关链路通了。没收到的话按顺序排查hermes gateway status看服务是否在跑journalctl -u hermes-gateway -n 50看日志有没有鉴权错误或连接超时确认 config.toml 里[gateway]段的enabled是true。网关场景下模型调用走的还是同一份 TaoToken 配置所以 TUI 能通、网关一般也能通。如果网关报模型错误但 TUI 正常多半是网关服务启动时没读到环境变量。系统服务不会自动继承你 shell 里的TAOTOKEN_API_KEY需要在 service 文件里加Environment或者在 config.toml 里临时用明文 Key 验证一下确认是环境变量问题后再改回安全方式。6. 本篇常见错排查报 401 或 invalid api keyKey 复制时带了空格或者环境变量没生效。echo $TAOTOKEN_API_KEY确认输出注意前后不要有换行。如果 Key 是在 TaoToken 控制台刚创建的确认没有误删。报 model not foundconfig.toml 里的模型名和 TaoToken 实际支持的名称不一致。模型名区分大小写去控制台或文档核对。default_model和[provider.taotoken.models]里的名字要能对上。TUI 能回复但网关不回先看hermes gateway status服务没跑就hermes gateway restart。服务在跑但不回看日志里有没有connection refused或timeout通常是服务器出站网络或防火墙问题确认能访问https://taotoken.net/api。hermes 命令找不到安装脚本写入了 shell 配置但当前会话没加载。source ~/.bashrc或source ~/.zshrc或者直接开一个新终端。记忆不生效检查memory_enabled是否为true以及~/.hermes/memory/目录是否有写权限。用 root 跑过之后再用普通用户跑可能因为目录属主问题写不进去。想换模型但不想改配置TUI 里用/model命令临时切换重启后回到default_model。要永久换改 config.toml 里的default_model然后重启 Hermes。如果你打算长期跑编码类任务或者接 Agent 工作流可以看下 Coding Plan额度模型和按量计费不太一样适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteKey 管理和用量查看都在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite需要新建或轮换 Key 时走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite配置过程中如果卡在某个报错先回接入文档对照请求格式大部分问题出在 base_url 多写了斜杠或者模型名拼错https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite