企业官网建设流程全解析

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/v3，Hermes 拼出来的完整地址就变成了https://ark.cn-beijing.volces.com/api/plan/v3/models。

问题来了：这个/models发现接口，在火山 Agent Plan 这套 plan 协议下并不按 Hermes 预期的方式返回模型列表。结果就是——模型其实能调用，但 Hermes 自动发现不到。于是它退回到配置里的默认模型glm-latest，Telegram 里自然只显示这一个。

所以这不是「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。填配置时不要在结尾加/models，Hermes 会自己拼，你加了反而重复。

第三样：模型清单。这是解决切换失效的核心。你需要知道火山 Agent Plan 下到底有哪些模型 ID 可用。常见的一批包括：

这份清单就是你要写进配置models:数组的内容。注意模型 ID 必须和火山后台的完全一致，大小写、连字符都不能错。写错一个，那个模型就切不过去。

关于 TaoToken 的补充。如果你除了火山 Agent Plan，还想接更多模型做对比或做 Agent 任务，可以了解下 TaoToken 这套方案。它的官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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，按Ctrl+O保存，Ctrl+X退出。

关于配置路径的提醒：不同安装方式路径可能不同。如果你找不到/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/v3，Key 是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-k3

Hermes 应该回你一句切换成功的提示，比如「已切换到 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是不是真的设成了false（YAML 里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.bak

Key 安全管理。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。四步走完，模型切换就稳了。