一个模型别名,三层各记各的:给 *-latest 对齐窗口、输出上限和思考强度时踩的 7 个坑
URL
date
Nov 16, 2026
slug
latest-alias-three-layers
summary
网关里建了模型别名只做完三分之一:两个 agent 框架各有一份清单,窗口、输出上限、思考强度要分别对齐。记 7 个坑和验证办法。
status
Published
tags
LLM
Hermes
OpenClaw
Sub2API
reasoning
type
Post

TL;DR
- 我在自建的 LLM 网关(Sub2API)里给每家模型建了两个别名,比如
claude-latest和claude-latest-flash。目的是模型换代时只改网关一行,用到它的地方都不用动。
- 别名建在网关里只做完了三分之一。用它的两个 agent 框架(Hermes 和 OpenClaw)各有一份自己的模型清单,窗口、输出上限、思考强度都记在各自那一份里,不会从网关继承。
- 最隐蔽的坑:请求被上游拒绝后,框架自动换到备用模型,回复看起来完全正常。判断一个名字通不通,要看日志里有没有它自己的调用记录,不能看有没有回复。
- 第二隐蔽的坑:配置里写的思考强度不等于实际发出去的。OpenClaw 会按模型把档位再调一次,要看请求回执和网关记录。
- 这次的活大部分是机械的:改几十个条目,每个发一次真实请求验证。强模型自己串着做又慢又乱,后来改成强模型写任务、便宜模型执行、强模型验收。
环境:网关 Sub2API 0.2.20(带本地补丁),OpenClaw 2026.11.3,Hermes v0.22.5。下面写的字段名和行为都是这几个版本上的,换版本要重新核对。
一、三层各管什么
- 网关(Sub2API):只管「别名指向哪个真实模型」。比如
gpt-latest-flash现在指向gpt-6.1-sol。
- Hermes:
config.yaml里每个 provider 有一份模型清单,记窗口(context_length)和输出上限(max_tokens)。思考强度是全局一个值(agent.reasoning_effort),另外可以按模型名单独覆盖(agent.reasoning_overrides)。
- OpenClaw:
openclaw.json里每个模型条目有reasoning开关、contextWindow、maxTokens。思考档位写在另一处(agents.defaults.models下每个模型的params.thinking)。每个 agent 还有自己的一份models.json,另有一份允许名单。
同一个别名,这三层各记各的。网关里加了一行,后两层什么都不会自动发生。

图里的三个盒子就是网关、Hermes、OpenClaw。它们之间不互相下发配置,每一处都要单独改。
二、七个坑
坑 1:别名在 OpenClaw 里默认不思考
现象:OpenClaw 里
*-latest 别名的 reasoning 是 false,而它们指向的模型是 true。原因:OpenClaw 的模型清单是一个同步脚本生成的。脚本里有一张规格表,表里没有别名,查不到就落到默认值 false。
修法:改脚本给新条目定 reasoning 的顺序。
- 是别名:取它指向的那个模型条目的值。
- 不是别名:带着思考强度向网关发一次真实请求,通过才写 true,不通过写 false。
这个脚本只管新加的条目。已经存在的条目它不改 reasoning,存量是另外逐条改的,每改一条发一次请求,不通过就改回 false。
结果:现在网关这两组下的 51 个模型里,5 个保持 false:3 个是开了之后真实请求被上游拒绝的,另外 2 个是指向其中两个的别名。改动到的条目都发过真实请求验证,大部分由子任务执行;原本就开着的没有逐个重测。配置里是 high 不等于实际发出去的是 high,见坑 4。
坑 2:Claude 的别名带不上思考参数
OpenClaw 按模型的名字决定给 Claude 发哪种思考参数。别名的名字它不认识,就按旧写法发。
- 指向 Opus 5.5 的别名:上游直接返回 400,原文是
claude-opus-5-5 requires adaptive thinking; omit thinking or use thinking.type=adaptive and output_config.effort。只删掉 thinking、保留 reasoning true,还是 400。
- 指向 Fable 的别名:请求能通,配置写着 true 加 high,但网关记录里它的思考强度一直是空的。
修法:在别名的模型条目上加一条能力声明。
"params": {"claudeCapabilities": {"adaptiveThinking": true}}加完后两个别名各发了两次,网关记到的思考强度都是 high。
风险:这个字段是读程序代码找到的。我没有查它是不是官方文档里的正式用法,所以 OpenClaw 每次升级后要复查一遍。
坑 3:设全局默认档位,会把一些模型拉低
OpenClaw 有一个全局默认思考档位
agents.defaults.thinkingDefault。设成 high 之后,没单独写档位的模型都按 high 走,以后新加的模型不写也是 high。取档的先后顺序是读程序看到的:agent 自己的默认档位,先于模型条目上的档位,再到全局默认,最后才是程序按模型给的默认。所以某个 agent 如果自己设了档位,模型条目上写什么对它都不起作用。
副作用:有两个没写档位的模型,设之前回执里是 max,设之后变成了 high。
做法:改全局默认之前,对没写档位的模型各发一次请求,记下回执里的档位;改完再发一次对比。
坑 4:配置写的档位,不等于实际发出去的
OpenClaw 的请求回执里有一项
thinkingClamp,写明「要的是哪一档、实际发的是哪一档」。这次见到两种:- reasoning 为 false 的模型:要 high,实际发的是 off。
- 有个模型配置写 xhigh,实际发的是 high。
回执里长这样(第一种情况的原文):
"requestShaping": {
"thinking": "off",
"thinkingClamp": "Thinking level clamped to off for sub2api/qwen-latest (requested high; preference retained)."
}拿回执的办法:用 OpenClaw 的命令行给指定模型发一条不投递的测试消息,输出里就有这一段。每次用一个新的会话名,免得写进正在用的会话。
openclaw agent --agent main --model sub2api/qwen-latest \
--session-key "agent:main:probe-$(uuidgen)" --json -m "Reply with exactly: OK"所以判断某个模型实际用哪一档,看回执和网关记录,不看配置文件。
坑 5:请求被拒后悄悄换了模型,回复看着正常
这个坑在 Hermes 这边。qwen 的两个别名在全局强度 high 下被上游拒绝:
'reasoning_effort' and 'thinking_budget' cannot be set simultaneouslyHermes 随后自动换到备用链上的第一个模型,回了一句正常的话。日志里是连着的两行(备用模型名已脱敏):
API call failed (attempt 1/3, not retryable) error_type=BadRequestError ... model=qwen-latest summary=HTTP 400: ...
Fallback activated: qwen-latest → <备用模型>如果验证脚本只看「有没有回复」,这两个别名就算通过了,实际上答话的根本不是 qwen。
我把其它档位也试了一遍,只有 low 能通。于是按模型名单独设成 low:
agent:
reasoning_effort: high
reasoning_overrides:
qwen-latest: low
qwen-latest-flash: low判据改成两条:日志里要有这个名字自己的
API call #1: model=模型名 这一行;同一次会话里没有换备用模型的记录。坑 6:说「没登记」之前,先说是哪一层
我问 agent 某两个别名是不是没加,它答「sub2api 下没有」。我明明记得让它加过,翻出当初的对照表去问,才弄清楚:网关里早就有,OpenClaw 里也有,缺的只是 Hermes 自己那份清单。
而且没登记也照样能用。没登记的名字解析出来的窗口,和这个 provider 的默认窗口相同,只是没有写明输出上限。
同一类的误读还有一次。Hermes 日志里有一行说 provider advertises 131,072,agent 把它报成了「网关公布的窗口更小」。查了才知道,那个数是 Hermes 按模型名从本机资料里猜的,网关的模型列表里根本没有窗口这一项。实际生效的是配置里写的数。
教训:系统有好几层的时候,回答「有没有」之前先说清查的是哪一层。
坑 7:Hermes 里 /model default 不是「回到默认」
我在聊天里发
/model default,以为是切回全局默认模型。实际上 default 被当成一个字面的模型名切了过去,回执里的窗口是 256,000,那是查不到规格时的兜底值。要切回去,写模型的真名:
/model 模型名 --provider provider名。三、怎么验证一个别名(最小流程)
- 记下当前时间。
- 用框架自己的命令给这个名字发一条最短的消息。Hermes 是
hermes chat -q '只回复 PONG' --oneshot -m 模型名 --provider provider名;OpenClaw 是坑 4 里那条命令。
- 看框架这一侧:Hermes 的 agent.log 里,这个时间之后要有
API call #1: model=模型名,同一次会话里没有Fallback activated;OpenClaw 的输出里,实际使用的模型是指定的那个,没有降级,再读requestShaping。
- 看网关这一侧:在网关的用量表里,按「请求的模型名」和这个时间之后取行,读「上游模型」和「请求的思考强度」两列。
- 三样对得上才算通过:框架收到了这个名字自己的成功回复、没有换备用的记录、网关有对应的一行。网关表里查不到行时先别下结论:我这里被上游拒绝的请求不进这张表,但查询条件写错也会查不到,要回到第 3 步看框架日志里的报错。
文中哪些是实测、哪些是读代码:
- 实测(发了请求,读了日志或网关记录):坑 2 修好后的结果、坑 3 的前后对比、坑 4 的两种回执、坑 5、cron 的默认模型和单独指定各一次测试任务。
- 读代码得出、没有做故障实测:坑 3 的取档顺序、坑 2 那个能力声明字段的来历、「指定了模型的任务不走全局备用链」。
- 网关带两处本地补丁(一处管模型目录,一处管系统消息的转发)。本文的结论我没有在不带补丁的官方版上验证过。
四、定时任务用哪个模型
别名理顺之后,第一个用上它的地方是定时任务(cron):默认模型写成别名,换代时 cron 就不用跟着改。顺带定了三条:
- agent 模式的任务不逐个指定模型,统一跟 cron 的默认走。默认用别名
gpt-latest-flash,以后换代不用改 cron。
- 只有轻重不同的才单独指定。每日复盘、每周复盘、会前准备这三个重任务固定用强模型。
- 单独指定是有代价的:指定了模型的任务不走全局备用链。这是读调度程序看到的,故障场景我没有实测。
验证方法:建一个一次性的测试任务,投递到本地,真跑一次,看日志里实际用的模型,跑完删掉。
五、怎么改才不出事
- 每次改之前备份,但不要整份拷回。 同一份配置文件一天里留下了 12 个备份。整份拷回会把后面的改动一起冲掉,只能按条目改回去。
- 每个改到的条目发一次真实请求。 三个判据:实际用的模型就是指定的那个;没有换到备用;网关记录的思考强度是预期值。
- 开不了的就保持关闭,把报错原文记下来。 不为了「全部是 true」硬开。
六、强模型写任务,便宜模型执行,强模型验收
上面这些改动加起来是几十个条目、每个都要发请求验证。分工方式对耗时影响很大,所以单独写一节。

一开始是主模型(强模型)什么都自己查、自己改。后来改成三段:
- 强模型写任务书:目标、输入、能改什么、交付什么、怎么验收、什么时候停。
- 便宜模型按任务书执行。
- 强模型读目标系统的真实状态来验收,不照抄子任务的报告。
这套做法自己也踩了四个坑:
- 任务书让子任务先造工具。 第一个子任务被要求先写一个通用脚本再执行。它 12 分钟只写了脚本,一条配置都没改,期间我改了三次目标。后来任务书直接写明最终值和要用的现成脚本,就顺了。
- 急的和不急的放在同一个任务里。 子任务全部做完才回报,已经修好的结果晚到了约 20 分钟。急的修复要单独一个任务。
- 子任务自报全部通过。 子任务报告里的结果,主模型没有逐项重测。汇报里要写清哪些是自己核的,哪些是照子任务报告说的。
- 主模型验收时又串着干。 有一轮它把验收、一项新改动、另一个新任务串在一起做,42 分钟没回一句话,验收脚本前后跑了 6 轮。做完一件先报一件。
现在的规矩:简单问题直接答;要动手的复杂活才走三段;验收只补能区分成功和失败的那几项检查。
七、清单:加一个新别名要做的事
- 网关:加路由,发一次请求,确认转到了目标模型。
- Hermes:在 provider 的模型清单里登记窗口和输出上限。发一次请求,看日志里有它自己的调用行,再看网关记录的思考强度。