一个模型别名,三层各记各的:给 *-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

  1. 我在自建的 LLM 网关(Sub2API)里给每家模型建了两个别名,比如 claude-latest 和 claude-latest-flash。目的是模型换代时只改网关一行,用到它的地方都不用动。
  1. 别名建在网关里只做完了三分之一。用它的两个 agent 框架(Hermes 和 OpenClaw)各有一份自己的模型清单,窗口、输出上限、思考强度都记在各自那一份里,不会从网关继承。
  1. 最隐蔽的坑:请求被上游拒绝后,框架自动换到备用模型,回复看起来完全正常。判断一个名字通不通,要看日志里有没有它自己的调用记录,不能看有没有回复。
  1. 第二隐蔽的坑:配置里写的思考强度不等于实际发出去的。OpenClaw 会按模型把档位再调一次,要看请求回执和网关记录。
  1. 这次的活大部分是机械的:改几十个条目,每个发一次真实请求验证。强模型自己串着做又慢又乱,后来改成强模型写任务、便宜模型执行、强模型验收。
环境:网关 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 simultaneously
Hermes 随后自动换到备用链上的第一个模型,回了一句正常的话。日志里是连着的两行(备用模型名已脱敏):
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名。

三、怎么验证一个别名(最小流程)

  1. 记下当前时间。
  1. 用框架自己的命令给这个名字发一条最短的消息。Hermes 是 hermes chat -q '只回复 PONG' --oneshot -m 模型名 --provider provider名;OpenClaw 是坑 4 里那条命令。
  1. 看框架这一侧:Hermes 的 agent.log 里,这个时间之后要有 API call #1: model=模型名,同一次会话里没有 Fallback activated;OpenClaw 的输出里,实际使用的模型是指定的那个,没有降级,再读 requestShaping。
  1. 看网关这一侧:在网关的用量表里,按「请求的模型名」和这个时间之后取行,读「上游模型」和「请求的思考强度」两列。
  1. 三样对得上才算通过:框架收到了这个名字自己的成功回复、没有换备用的记录、网关有对应的一行。网关表里查不到行时先别下结论:我这里被上游拒绝的请求不进这张表,但查询条件写错也会查不到,要回到第 3 步看框架日志里的报错。
文中哪些是实测、哪些是读代码:
  • 实测(发了请求,读了日志或网关记录):坑 2 修好后的结果、坑 3 的前后对比、坑 4 的两种回执、坑 5、cron 的默认模型和单独指定各一次测试任务。
  • 读代码得出、没有做故障实测:坑 3 的取档顺序、坑 2 那个能力声明字段的来历、「指定了模型的任务不走全局备用链」。
  • 网关带两处本地补丁(一处管模型目录,一处管系统消息的转发)。本文的结论我没有在不带补丁的官方版上验证过。

四、定时任务用哪个模型

别名理顺之后,第一个用上它的地方是定时任务(cron):默认模型写成别名,换代时 cron 就不用跟着改。顺带定了三条:
  1. agent 模式的任务不逐个指定模型,统一跟 cron 的默认走。默认用别名 gpt-latest-flash,以后换代不用改 cron。
  1. 只有轻重不同的才单独指定。每日复盘、每周复盘、会前准备这三个重任务固定用强模型。
  1. 单独指定是有代价的:指定了模型的任务不走全局备用链。这是读调度程序看到的,故障场景我没有实测。
验证方法:建一个一次性的测试任务,投递到本地,真跑一次,看日志里实际用的模型,跑完删掉。

五、怎么改才不出事

  1. 每次改之前备份,但不要整份拷回。 同一份配置文件一天里留下了 12 个备份。整份拷回会把后面的改动一起冲掉,只能按条目改回去。
  1. 每个改到的条目发一次真实请求。 三个判据:实际用的模型就是指定的那个;没有换到备用;网关记录的思考强度是预期值。
  1. 开不了的就保持关闭,把报错原文记下来。 不为了「全部是 true」硬开。

六、强模型写任务,便宜模型执行,强模型验收

上面这些改动加起来是几十个条目、每个都要发请求验证。分工方式对耗时影响很大,所以单独写一节。
示意:写任务书、执行、验收三段
示意:写任务书、执行、验收三段
一开始是主模型(强模型)什么都自己查、自己改。后来改成三段:
  • 强模型写任务书:目标、输入、能改什么、交付什么、怎么验收、什么时候停。
  • 便宜模型按任务书执行。
  • 强模型读目标系统的真实状态来验收,不照抄子任务的报告。
这套做法自己也踩了四个坑:
  1. 任务书让子任务先造工具。 第一个子任务被要求先写一个通用脚本再执行。它 12 分钟只写了脚本,一条配置都没改,期间我改了三次目标。后来任务书直接写明最终值和要用的现成脚本,就顺了。
  1. 急的和不急的放在同一个任务里。 子任务全部做完才回报,已经修好的结果晚到了约 20 分钟。急的修复要单独一个任务。
  1. 子任务自报全部通过。 子任务报告里的结果,主模型没有逐项重测。汇报里要写清哪些是自己核的,哪些是照子任务报告说的。
  1. 主模型验收时又串着干。 有一轮它把验收、一项新改动、另一个新任务串在一起做,42 分钟没回一句话,验收脚本前后跑了 6 轮。做完一件先报一件。
现在的规矩:简单问题直接答;要动手的复杂活才走三段;验收只补能区分成功和失败的那几项检查。

七、清单:加一个新别名要做的事

  1. 网关:加路由,发一次请求,确认转到了目标模型。
  1. Hermes:在 provider 的模型清单里登记窗口和输出上限。发一次请求,看日志里有它自己的调用行,再看网关记录的思考强度。

© Ying Bun 2021 - 2026