1. Hermes 接入火山 Agent Plan 后模型切换失效问题场景与链路拆解Hermes 是一个可以跑在云服务器上的多模型 Agent 网关它把 Telegram、Web 等入口和背后的模型服务串起来让你在聊天窗口里用/model命令切换不同的大模型。火山 Agent Plan 则是火山引擎提供的一套模型调用方案一个 API Key 背后挂着 doubao、deepseek、glm、minimax、kimi 等多个模型。把这两者接起来理论上你就能在 Telegram 里一句话切换模型做代码、写文案、跑 Agent 任务都方便。但实际接的时候很多人会撞上一个很典型的问题Hermes 无法切换火山 Agent Plan 模型。表现是——火山 Agent Plan 后台明明开了十几个模型可你在 Telegram 里发/model列表里只孤零零显示一个glm-latest其他模型一个都看不到更别说切过去。你手动发/model kimi-k3它要么没反应要么回你一句不支持。这个场景特别容易出现在「腾讯云服务器 → Hermes → 火山 Agent Plan → Telegram」这条链路上。因为中间隔了好几层报错信息又不会直接告诉你「是模型发现接口挂了」所以新手很容易卡在这里以为是 Key 错了、网络不通、或者火山那边没开通模型。我先把这条链路拆开讲清楚你就能明白问题出在哪一环。整条链路是这样的你在 Telegram 发/model→ Hermes 收到命令 → Hermes 去问火山 Agent Plan「你有哪些模型」→ 火山返回模型列表 → Hermes 把列表渲染成按钮或文本 → 你在 Telegram 看到可选模型。关键就在第三步。Hermes 默认会去请求一个「模型列表」接口路径是拼在 Base URL 后面的/models。而火山 Agent Plan 的 Base URL 是https://ark.cn-beijing.volces.com/api/plan/v3Hermes 拼出来的完整地址就变成了https://ark.cn-beijing.volces.com/api/plan/v3/models。问题来了这个/models发现接口在火山 Agent Plan 这套 plan 协议下并不按 Hermes 预期的方式返回模型列表。结果就是——模型其实能调用但 Hermes 自动发现不到。于是它退回到配置里的默认模型glm-latestTelegram 里自然只显示这一个。所以这不是「Key 无效」也不是「模型没开通」而是模型发现discover_models机制和火山 Agent Plan 的接口不兼容。理解了这一点解决思路就清晰了既然自动发现不靠谱那就关掉自动发现改成手动把模型列表写进配置里。这样 Hermes 不再去问火山「你有啥模型」而是直接读你写死的清单/model就能列出全部模型并正常切换。下面我会按「前置准备 → 可复制配置 → 验证请求 → 常见报错排查」的顺序把每一步都写清楚你照着做就能复现并确认模型切换是否生效。适合已经有一台云服务器、装好 Hermes、并且拿到火山 Agent Plan API Key 的同学。如果你还没拿到 Key我也会在第二节说明怎么准备。2. TaoToken 前置准备API Key、Base URL 与模型清单怎么备齐在动配置文件之前先把「弹药」备齐。这一步做扎实后面改配置就是几分钟的事。你需要准备三样东西一个可用的 API Key、正确的 Base URL、以及一份你想开放的模型清单。第一样API Key。火山 Agent Plan 的 Key 一般以ark-开头形如ark-xxxxxxxx。这个 Key 是你在火山控制台开通 Agent Plan 后生成的。注意Agent Plan 的 Key 和普通方舟推理的 Key 可能不是同一个入口别拿错了。拿到后先记下来等会填进配置的api_key字段。第二样Base URL。火山 Agent Plan 的 Base URL 是https://ark.cn-beijing.volces.com/api/plan/v3这个地址很关键注意结尾是/api/plan/v3不是/api/v3。很多人抄错成普通方舟的地址结果协议对不上模型调用直接 404。填配置时不要在结尾加/modelsHermes 会自己拼你加了反而重复。第三样模型清单。这是解决切换失效的核心。你需要知道火山 Agent Plan 下到底有哪些模型 ID 可用。常见的一批包括模型 ID说明auto自动路由doubao-seed-2.0-mini豆包轻量版doubao-seed-2.0-lite豆包精简版doubao-seed-2.0-pro豆包专业版doubao-seed-2.0-code豆包代码版deepseek-v4-flashDeepSeek 快速版deepseek-v4-proDeepSeek 专业版deepseek-v3.2DeepSeek V3.2glm-latestGLM 最新版minimax-m2.7MiniMax M2.7minimax-m3MiniMax M3kimi-k2.6Kimi K2.6kimi-k3Kimi K3这份清单就是你要写进配置models:数组的内容。注意模型 ID 必须和火山后台的完全一致大小写、连字符都不能错。写错一个那个模型就切不过去。关于 TaoToken 的补充。如果你除了火山 Agent Plan还想接更多模型做对比或做 Agent 任务可以了解下 TaoToken 这套方案。它的官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它提供统一的模型接入方式适合需要长期跑编码、Agent 任务的场景。你可以先拿火山 Agent Plan 把 Hermes 跑通再考虑要不要扩展。前置检查清单服务器能访问ark.cn-beijing.volces.com用curl -I测一下Hermes 已安装并能启动hermes --version有输出拿到ark-开头的 Key确认火山后台已开通你要用的模型记下 Hermes 配置文件路径通常是/home/ubuntu/.hermes/config.yaml这里有个小坑.hermes是隐藏目录用ls看不到得用ls -a或者直接cat /home/ubuntu/.hermes/config.yaml。如果你用的是 root 用户路径可能是/root/.hermes/config.yaml。先确认路径再动手改。备齐这些就可以进入下一步改配置了。记住核心思路关掉自动发现手动写死模型清单。3. 可复制配置修改 Hermes config.yaml 关闭模型自动发现这一步是解决问题的关键。我们要在 Hermes 的配置文件里为火山 Agent Plan 单独定义一个 provider并且把discover_models设为false同时手动列出所有模型。先找到配置文件。在服务器上执行ls -a /home/ubuntu/.hermes/如果看到config.yaml就对了。用你顺手的编辑器打开比如nano /home/ubuntu/.hermes/config.yaml或者vim /home/ubuntu/.hermes/config.yaml然后在配置里加入或修改下面这段。注意 YAML 的缩进必须用空格不能用 Tab缩进错了 Hermes 启动会直接报解析错误。custom_agent_plan: base_url: https://ark.cn-beijing.volces.com/api/plan/v3 protocol: api_key: ark-MYKEY api_mode: chat_completions model: glm-latest default_model: glm-latest model_display_name: GLM Latest on Agent Plan discover_models: false models: - auto - doubao-seed-2.0-mini - doubao-seed-2.0-lite - doubao-seed-2.0-pro - doubao-seed-2.0-code - deepseek-v4-flash - deepseek-v4-pro - deepseek-v3.2 - glm-latest - minimax-m2.7 - minimax-m3 - kimi-k2.6 - kimi-k3逐项解释一下这些字段方便你按自己情况调整base_url就是火山 Agent Plan 的地址结尾到/v3为止别加/models。protocol留空字符串。有些版本 Hermes 需要显式留空来走默认协议填错反而出问题。api_key换成你自己的ark-Key。注意别把 Key 提交到公开仓库这是敏感信息。api_mode设为chat_completions因为火山 Agent Plan 走的是 OpenAI 兼容的 chat completions 协议。model和default_model都设成glm-latest这是默认模型也是你/model不指定时用的那个。model_display_name是显示名随便起Telegram 里会显示这个。discover_models: false是整件事的核心。设为 false 后Hermes 不再去请求/models接口而是直接读下面的models列表。这样火山 Agent Plan 那个不兼容的发现接口就被绕过了。models数组就是你要开放的模型清单按上一节的表格填。你可以只留常用的几个也可以全列上。列得越多/model里能切的就越多。改完保存。如果你用的是nano按CtrlO保存CtrlX退出。关于配置路径的提醒不同安装方式路径可能不同。如果你找不到/home/ubuntu/.hermes/config.yaml试试find / -name config.yaml -path *hermes* 2/dev/null这条命令会帮你定位真实的配置文件位置。如果你用的是 Codex 或 Cline 这类工具配置思路类似但字段不同。以 Codex 的auth.json为例它需要三件套Base URL、Key、Model ID。Base URL 同样是https://ark.cn-beijing.volces.com/api/plan/v3Key 是ark-开头Model ID 从上面的清单里选。Cline 的 MCP 配置也是同理把这三样填对模型就能调起来。核心永远是Base URL 别写错、Key 别过期、Model ID 别拼错。配置改完先别急着高兴下一步要重启并验证。4. 验证请求重启 Hermes 并用 /model 确认切换生效配置写好了但 Hermes 不会自动加载新配置必须重启。这一步很多人会漏改完配置发现没变化就是因为没重启。在服务器上执行hermes gateway restart如果这条命令报「command not found」说明 Hermes 的可执行文件不在 PATH 里试试~/.local/bin/hermes gateway restart或者先which hermes找到路径再执行。重启成功的标志是终端输出类似gateway restarted的提示没有报错。重启后回到 Telegram先发一个/new这个命令会开一个新的会话确保你用的是最新配置而不是旧会话的缓存。很多人改了配置但没/new结果还是老样子白折腾。然后发/model这时候你应该能看到一个模型列表里面有你配置里写的所有模型比如kimi-k3、minimax-m3、deepseek-v4-pro等等而不是只有一个glm-latest。如果列表出来了恭喜模型发现的问题解决了。接下来测试切换。直接发/model kimi-k3Hermes 应该回你一句切换成功的提示比如「已切换到 Kimi K3」之类。然后你随便发一句话比如「你好你是谁」看回复是不是来自 Kimi K3。不同模型的回答风格不一样你可以借此确认真的切过去了。再测一个/model deepseek-v4-pro同样发一句话验证。如果两个模型都能正常切换并回复说明整条链路通了。验证请求是否真的打到火山 Agent Plan。如果你想更严谨可以在服务器上看 Hermes 的日志。日志里会记录每次请求的 URL 和模型 ID。执行tail -f /home/ubuntu/.hermes/logs/gateway.log然后在 Telegram 发一句话观察日志里有没有类似POST https://ark.cn-beijing.volces.com/api/plan/v3/chat/completions的记录以及请求体里的model字段是不是你刚切的模型。这一步能帮你确认请求真的发出去了而不是被本地缓存拦下。设置模型别名让切换更快。如果你经常切某几个模型可以在配置里加别名。比如aliases: kimi3: kimi-k3 mmx3: minimax-m3 ds: deepseek-v4-pro ap: glm-latest加完重启后你就能用/kimi3直接切到 Kimi K3用/mmx3切到 MiniMax M3省得每次打全名。别名配置在不同 Hermes 版本里字段名可能略有差异如果aliases不生效查一下你那个版本的文档有的版本叫model_aliases。成功结果长这样/model列出全部模型 →/model kimi-k3切换成功 → 发消息得到 Kimi K3 的回复 → 日志里能看到对应请求。四步都过就彻底通了。如果某一步没过别慌下一节我把常见报错和排查路径列出来。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 问题即使配置写对了实际跑的时候还是可能撞上各种报错。这一节我把 Hermes 接火山 Agent Plan 时最常见的几类错误列出来对照着排查。报错一401 Unauthorized。这是最直白的Key 不对。可能原因Key 复制时多了空格、Key 已过期、Key 不是 Agent Plan 的而是普通方舟的。排查方法把 Key 单独拿出来用 curl 直接测curl https://ark.cn-beijing.volces.com/api/plan/v3/chat/completions \ -H Authorization: Bearer ark-MYKEY \ -H Content-Type: application/json \ -d {model:glm-latest,messages:[{role:user,content:hi}]}如果这条 curl 也返回 401那就是 Key 本身的问题去火山控制台重新生成。如果 curl 通了但 Hermes 报 401那就是配置里的 Key 写错了检查api_key字段有没有多余字符。报错二local proxy failed。这个错误通常出现在 Hermes 尝试通过本地代理转发请求时。可能原因服务器上配了 HTTP_PROXY 环境变量但代理不可用或者 Hermes 的代理配置和实际网络环境不匹配。排查方法先检查环境变量env | grep -i proxy如果有HTTP_PROXY或HTTPS_PROXY而你的服务器其实不需要代理就 unset 掉unset HTTP_PROXY HTTPS_PROXY然后重启 Hermes。注意这里说的是服务器本地的网络配置问题不是让你去搞什么特殊网络手段纯粹是排查环境变量冲突。报错三reading choices 相关错误。完整报错可能是error reading choices或cannot read property choices of undefined。这说明 Hermes 收到了响应但响应结构里没有它预期的choices字段。常见原因是api_mode设错了。火山 Agent Plan 走的是chat_completions如果你设成了别的模式比如 responses 模式返回结构就对不上。检查配置里api_mode: chat_completions有没有写对。另一个可能是模型 ID 写错了火山返回了一个错误对象而不是正常响应。用上面那条 curl 换成你切的模型 ID 测一下看返回结构。报错四OAuth 相关错误。如果你在配置里误开了 OAuth 认证或者 Hermes 版本默认走了 OAuth 流程会报 token 获取失败之类的错。火山 Agent Plan 用的是 API Key 认证不需要 OAuth。检查配置里有没有oauth相关字段有的话删掉或设为 false。确保认证方式走的是api_key。报错五/model 还是只显示一个模型。如果重启也做了、/new也发了列表还是只有一个检查三件事一是discover_models是不是真的设成了falseYAML 里false不能加引号写成false会被当成字符串真值二是models数组的缩进对不对YAML 对缩进极其敏感三是配置文件路径对不对你可能改了另一个 config.yaml。用hermes config path之类的命令确认当前加载的是哪个文件。排查通用思路先看 Hermes 日志日志里通常有完整的请求 URL 和响应体比猜快得多。然后拿 curl 直接测火山接口把 Hermes 这一层剥掉确认火山那边是通的。最后再回头查 Hermes 配置。这个「从外到内」的顺序能帮你快速定位问题在哪一层。如果你排查下来发现是接入方式本身的问题需要更统一的模型接入方案可以看 TaoToken 的接入文档地址在 https://taotoken.net/api 里面有 Base URL、Key、Model ID 三件套的完整说明。排障阶段建议先把 API Key 和接入文档过一遍确认基础配置无误。6. 长期跑编码与 Agent 任务把模型切换用顺手的几个实践模型切换通了之后怎么把它用顺手是另一回事。这一节聊几个实践帮你把 Hermes 火山 Agent Plan 这套组合真正用起来。按任务类型选模型。不同模型擅长的方向不一样。写代码可以优先用doubao-seed-2.0-code或deepseek-v4-pro长文写作和总结用kimi-k3或glm-latest需要快速响应的轻量任务用doubao-seed-2.0-mini或deepseek-v4-flash。你可以把常用的几个设成别名切换时一个命令搞定。比如把ds设成deepseek-v4-pro写代码时/ds一下比翻列表快。用 auto 做兜底。配置里的auto模型是自动路由适合你不确定用哪个模型的时候。它会根据任务自动选一个。日常闲聊、简单问答用auto就行省心。Agent 任务注意上下文长度。跑 Agent 任务时对话轮次多、上下文长要选上下文窗口大的模型。kimi-k3、deepseek-v4-pro这类通常窗口更大。如果任务跑到一半报上下文超限换个窗口大的模型重试。长期编码场景考虑 Coding Plan。如果你主要是拿这套组合做长期编码、跑 Agent可以了解下 TaoToken 的 Coding Plan入口在 https://taotoken.net/api 。它针对编码和 Agent 场景做了优化适合需要稳定长期调用的同学。模型对话功能可以在 https://taotoken.net/api 对应的控制台里体验先试再决定要不要长期用。配置备份。改好的config.yaml记得备份一份。Hermes 升级或重装时配置文件可能被覆盖。备份命令cp /home/ubuntu/.hermes/config.yaml /home/ubuntu/.hermes/config.yaml.bakKey 安全管理。api_key是明文写在配置里的注意服务器权限。把配置文件权限收紧chmod 600 /home/ubuntu/.hermes/config.yaml这样只有文件所有者能读写其他用户看不到你的 Key。定期检查模型清单。火山 Agent Plan 的模型会更新新模型上线、旧模型下线都有可能。隔一段时间去火山控制台看看把新模型加进models数组把下线的删掉。不然/model里会出现切不过去的死模型。日志轮转。长期跑的话Hermes 日志会越来越大。配个 logrotate或者定期手动清理truncate -s 0 /home/ubuntu/.hermes/logs/gateway.log这条命令把日志清空但保留文件比直接删安全。最后说个我踩过的坑改完配置一定要/new开新会话再测。我有次改完配置重启了但一直在旧会话里发/model怎么都不生效折腾半天才发现是会话缓存。记住这个顺序改配置 → 重启 →/new→/model。四步走完模型切换就稳了。