1. 从一个卡死的下午说起：HagiCode为什么必须多模型化
上个月的一个下午，我正开着 HagiCode 给一个老项目改接口文档，结果它默认绑定的那个模型突然开始吐乱码。检查后台一看，token 配额在零点的定时任务里被跑光了，离重置还有十几个小时。那天下午我不得不切回裸终端写代码，效率直接对半砍。也就是那个下午，我下定决心：凡是接进 HagiCode 的模型，绝不能只有一个。
HagiCode 这个工具，熟悉我的朋友都知道，它是一个本地优先的 AI 辅助编程工具，核心思路是把编辑器、终端和模型网关捏在一起。平时我用它做代码补全、批量重构、commit message 生成，甚至让它直接跑 Agent 任务改文件。之前它只绑了一个模型，心里总是不踏实——模型服务商一限流、一调价、一抽风，我的工作流就跟着完蛋。多模型支持不是锦上添花，是刚需。
正好那段时间，智谱把 GLM 系列的开放接口做得越来越顺手，还推出了 glm coding plan 这类专门给编程场景设计的套餐，7 天体验卡拿来做测试也很方便；另一边 Gemini CLI 在命令行环境里的表现也确实亮眼，尤其在长链路代码理解和多文件改动上，推理质量能感觉到明显优势。于是我把 HagiCode 的模型层重做了一遍，让它同时接入 GLM 和 Gemini CLI，形成了一套可以随时切换、按场景分流的双模型架构。
这篇博文不打算说太虚的东西，就把我这一个多月从调研、接入、配置、实测到踩坑的全过程摊开讲。如果你也在用一个支持多模型的编程工具，或者正琢磨着怎么把 GLM、Gemini CLI 这类能力吃进来，这篇文章应该能帮你省掉不少弯路上的时间。
先说清楚两个前提：第一，HagiCode 本身是支持自定义模型提供方的，这决定了我们不需要去改它源码，只做配置层的接入；第二，GLM 和 Gemini CLI 走的是两条完全不同的接入路径，前者是标准的 HTTP API，后者是本地命令行进程，这两条路在 HagiCode 里要用完全不同的适配逻辑。理解了这两点，后面所有操作就都顺理成章了。
2. GLM 接入的本质：先把"OpenAI 兼容"这层窗户纸捅破
2.1 GLM 的 API 形态与 HagiCode 模型配置的关系
GLM 开放平台对外提供的接口是 OpenAI 兼容格式，这是个非常重要的信息。什么叫 OpenAI 兼容？就是说它把 HTTP 路径、请求体结构、流式返回格式都照着 OpenAI 的规范来实现，所以任何一个只要支持 OpenAI API 的客户端工具，理论上都可以通过改 base_url 和 model 名称直接对接 GLM，不需要为它写专门的 SDK 适配层。
HagiCode 的模型设置界面里，新增一个自定义模型提供方时，需要填的字段也就是那几个：API 地址、模型名称、密钥、上下文窗口大小。这意味着 GLM 接入 HagiCode 的工程成本比想象中低很多。核心配置逻辑其实就三步：拿到密钥、填对模型名、验证连通性。
我采用的配置方式是环境变量注入，而不是直接把密钥硬写在配置文件里。HagiCode 是本地工具，配置文件通常放在用户目录下，如果密钥明文写进去，一旦设备被同步到远端仓库就麻烦了。在 shell 配置文件里加一行：
export GLM_API_KEY="你的智谱API密钥"然后在 HagiCode 的模型配置里引用这个环境变量，既安全又方便换绑。具体到 GLM 这边，我用的是官方默认的 API 入口，再按照模型列表填对应的 model 字段。配置文件长这样：
model_providers: zhipu: api_base: https://open.bigmodel.cn/api/paas/v4/chat/completions api_key_env: GLM_API_KEY model: glm-5.3-flash context_window: 131072这里有个特别容易踩的坑：不同模型服务商对model字段的命名规则差异很大，有的要写glm-5.3-flash，有的要写带日期后缀的版本号，有的则只认不带特殊符号的别名。我第一次接 GLM 时就是因为图省事，把另一个平台上的旧模型名直接搬了过来，结果 HagiCode 一直报 404。排查了好久才发现是 model 名称对不上。在 GLM 接入里，字段名这种东西必须一字不差，多一个小写字母、少一个短横线都会直接失败。
2.2 流式响应与 tool calling 是编程助手的两条命脉
如果只是做简单对话，OpenAI 兼容接口的接入过程会非常顺利。但 HagiCode 是编程工具，它要做代码补全、要调用外部工具完成 Agent 任务，所以必须依赖两个关键能力：流式输出和函数调用（tool calling）。
流式输出大家都懂，就是让 Token 一个接一个返回，而不是等模型生成完毕再一次性吐出。这对交互体验影响极大。我在接入时特意测试了 GLM 的流式返回是否遵循标准的 SSE 格式，结论是遵循得挺好，HagiCode 打开流式开关后基本零改动就能用。
tool calling 是更核心的能力。HagiCode 让模型执行文件操作、调用终端命令时，需要模型先输出一个结构化的工具调用请求，然后 HagiCode 拿到这个请求去执行，再把结果送回给模型继续推理。这一来一回对 API 的兼容性要求非常高。
GLM 在 tool calling 上和 OpenAI 格式一致，请求体里的tools数组、tool_choice参数、响应的tool_calls字段都能对上。但我在实际调试中发现两个细节要注意：
- 多工具并行：GLM 在一次响应里可以返回多个 tool call，HagiCode 会并行执行。这个很实用，比如让模型同时读三个文件再综合判断。但并行数量我不建议开太大，实测超过五个会让上下文管理变得混乱。
- 工具结果回传：工具执行完，要把结果以
role: tool的消息追加到对话里。有些模型对这条消息的顺序要求严格，切到 Gemini 时就因为顺序不对出过问题，后面细说。
这两条命脉通了，GLM 接入 HagiCode 就已经完成了一大半，剩下的不过是配置和验证。
2.3 五分钟连通性测试
配置改完，最忌讳的是直接闷头开干。我建议先在 HagiCode 的命令行调试器里做一个基础连通性测试，用一条最简单的对话验证整个链路：
hagicode model:test --provider zhipu --prompt "只回复四个字：链路正常"预期结果是在几秒内收到流式返回的"链路正常"。如果这里就报错，先排查 API 地址、密钥、网络三个环节。如果正常返回但仍无法做代码补全，再检查是不是没开启流式开关，或者模型名写成了对话模型而非编程专用模型。
我实测下来，glm-5.3-flash作为日常编程使用的默认模型，响应速度是比较理想的，在代码补全场景下首字返回大概在几百毫秒到一秒出头之间。如果对代码理解能力要求更高，可以切到更大尺寸的模型，但相应地成本也会上升，怎么取舍后面实测账本里会讲。
3. Gemini CLI 集成：它不是用来替代 GLM 的，而是补上另一条腿
3.1 为什么选择命令行进程而不是直接打 API
Gemini CLI 这事的接入思路，和 GLM 完全不一样。GLM 走的是 API，在 HagiCode 的配置界面里填几个字段就能跑通；而 Gemini CLI 是一个本地命令行工具，有自己的登录态、会话管理、上下文整理逻辑和 Agent 能力。接入 HagiCode 时，我面临一个选择：是绕过 CLI 直接调 Gemini 的 API，还是让 HagiCode 和 Gemini CLI 进程协作。
我选择了后者。原因有三：
- Gemini CLI 的价值不在模型本身，而在它已封装好的 Agent 工作流。它自带文件读取、代码编辑、命令行执行等工具的编排逻辑，我直接调 API 等于要自己重新造一套，不划算。
- 本地进程协作可以复用已有的认证登录态。Gemini CLI 登录一次后，凭证存在本机，HagiCode 每次启动新任务时不需要重复走 OAuth 流程。
- 隔离性好。Gemini CLI 崩溃或超时，最多影响它自己那条调用链，不至于把 HagiCode 的主进程拖下水。
3.2 HagiCode 与 Gemini CLI 的进程协作模式
HagiCode 里把 Gemini CLI 注册成一个"本地命令行模型提供方"，配置文件是这么写的：
model_providers: gemini_cli: type: cli command: gemini-cli args: [--noproxy, --noauth_scripts] model: gemini-2.5-pro working_dir: "{project_dir}"原理不复杂：HagiCode 需要在让模型做特定推理时，用子进程方式拉起gemini-cli，把待处理的代码片段、用户指令以参数或标准输入传进去，然后从标准输出里截取返回结果，再按约定的格式解析回 HagiCode 内部的消息结构。
但真正落地时，有几个细节是文档里没有的：
工作目录必须实时切换。Gemini CLI 是围绕当前目录理解项目的，如果 HagiCode 同时打开了三个项目，而 Gemini CLI 的工作目录还停留在上一个项目里，它生成的代码路径就可能指向错的目录。我踩过一次：让它改 A 项目的文件，它却因为当前目录在 B 项目，在 B 项目里创建了一个同名文件。排查过程很痛苦，最后定位到是工作目录没跟着 HagiCode 的活动项目走。修复方式是在拉起子进程前，强制把cwd设为当前活动项目根目录。
标准输出未必干净。如果之前给 Gemini CLI 配置过日志输出、进度条美化之类的选项，它输出里会夹杂非结构化内容。HagiCode 解析结果时会把这些当噪音处理掉，但有时会误伤真正的代码内容。解决办法是在args里禁用掉一切非必要输出，保持进程输出的纯净。
长任务必须配合超时机制。Gemini CLI 处理一些大文件重构任务时会思考很久，如果 HagiCode 这边没有兜底超时，用户会以为卡死了。我设置的超时是 180 秒，超过就终止进程并提示用户是否重试。这个值可以根据项目大小调整，但不要设太大，让用户干等不好。
3.3 一个典型的分工场景：GLM 打前站，Gemini CLI 啃硬骨头
多模型接入不是让两个模型轮流跑，而是要发挥各自优势。我在 HagiCode 里定义了一套分工规则：
GLM 负责高频、低延迟、成本敏感的任务：行级代码补全、短对话问答、commit message 生成、简单正则替换。这些任务请求频率高，但单次负载低，用 GLM 的 flash 级别模型非常划算。
Gemini CLI 负责低频、高难度、长链路的任务：跨多文件的重构方案设计、理解一个陌生项目的整体结构、排查复杂的 bug 调用链。这类任务我需要它一次读很多文件、做多步推理，Gemini CLI 的 Agent 能力正好擅长这个。
实际操作时，我会在 HagiCode 的指令前缀里显式声明用哪个模型，比如：
/use gemini-cli 帮我梳理一下这个项目的依赖注入链路，指出循环依赖风险。HagiCode 根据这个前缀把任务路由给对应的模型。一开始我图省事想过"自动路由"，就是让 HagiCode 自己判断任务难度来决定用哪个模型。后来发现物极必反——自动判断的逻辑本身就有误判率，一个稍微复杂点的重构被发给了 GLM，推理了一半发现搞不定又切回 Gemini CLI，白白浪费了对话历史。最终还是人工指定模型最靠谱，因为开发者自己最清楚当前任务的难度。
4. 多模型同时在线：路由规则、上下文与成本的实测账本
4.1 我的模型分流原则和背后的逻辑
经过一个多月的实际使用，我总结出的分流原则就一句话：简单任务给便宜模型，复杂任务给聪明模型，两者切换要显式、要干净、不拖泥带水。
具体执行时，我还会给每个模型设定独立的对话会话。HagiCode 里不同模型之间不共享上下文，这反而是一个优点——GLM 那边的对话就算聊乱了，也不会污染 Gemini CLI 的上下文窗口。可千万别试图让两个模型共享同一段冗长的历史消息，那会让两边都变傻，同时让 token 消耗成倍增长。各管各的、保持会话隔离，是效率最高也最省钱的做法。
HagiCode 还支持为不同模型设置不同的 system prompt。GLM 的 system prompt 我写得比较精简，让它的行为接近一个敏捷的结对程序员，快速响应、不废话；Gemini CLI 的 system prompt 我会写长一些，要求它系统性地分析问题、列出方案选项后再动手，甚至在改动前先输出一个简短的 CLI 操作计划。
4.2 上下文窗口差异对实际任务的影响
上下文窗口是编程场景下最硬性的参数之一。GLM 这边，我用过的glm-5.3-flash提供了大约 128K 级别的上下文，在一些大仓库场景下够用但不算宽裕；而 Gemini CLI 背后的模型上下文窗口更大，在分析大型代码库时优势明显，即使塞进去十几个文件的全文，也不太会触发截断。
但上下文大不等于可以乱塞。我观察到，当单次会话注入的代码超过一定量级后，GPT 家族和 GLM 系列都会出现某种"中间遗忘"现象——对对话前部的指令遵循度下降。这个问题在两个模型上都出现过。所以我养成了一个习惯：长会话拆短会话，短会话聚焦单一任务。
比如我要重构一个模块，我不会让模型"从头到尾把这个模块看一遍再改"。我会先让 HagiCode 用 GLM 快速定位相关文件，然后把文件按依赖顺序分成几批，每批交给 Gemini CLI 做局部重构，每个局部任务控制在它最舒适的文件数量范围内。这样既避免了上下文拥挤，又让每一步的改动都可审查、可回滚。
4.3 成本账：GLM 的活动权益与 Gemini CLI 的调用开销
谈到成本，这个话题最有意思。我一直关注智谱的官方活动，比如 GLM 送 token 的活动，新用户注册能拿到免费额度，另外当时测试期间的 coding plan 7 天体验卡，基本上等于把主力编程模型免费给你用一周。我就在那 7 天里把 GLM 接入了 HagiCode，高强度使用了一周，对它的稳定性、延迟、代码质量都有了直观感受——这也是为什么后来它成了我的默认编程模型。
我对两个模型的日常消耗做了个简单统计。在一个中等强度的开发日里（约 6 小时的编码时间），GLM 侧的画面是：数千次基础补全请求，耗 token 在百万级，但由于用的是有活动权益的套餐，实际支出几乎可以忽略。Gemini CLI 侧则是另一个画面：它会激进地读取文件、生成大段代码，单次长任务的 token 消耗可能抵得上 GLM 几十次补全，但因为只在特定场景下用，每天调用次数有限。两者相加，总成本反而比之前单一绑一个高端模型要低，因为低价值请求不再占用高价格模型的额度了。
这是我在接完 GLM 之后才想明白的账：多模型的真正收益不只是"多一份保障"，更是"让每一类任务都跑在最合适的计费档次上"。模型不是越强越好，而是越匹配越好。
5. 五个最典型的接入故障：完整排查链路复盘
5.1 404 迷雾：模型名不一致问题
这是我接入 GLM 时遇到的第一个拦路虎。配置文件里我填了glm-4-air，这个模型名在别的平台上是存在的，但 GLM 官方接口不认识它，返回 404。刚开始我以为是 API 地址写错了，检查了三遍没问题，又怀疑是密钥失效，重新生成了一次还是不行。最后我把 API 请求原样打印出来，发现请求体里的 model 字段填的是一个不存在的模型名。
排查这条链路花了四十分钟，全耗在"想当然"上。正确的做法是先到官方模型列表页面确认可用的模型 ID，而不是凭记忆写。只要涉及模型名，一切以官方文档为准，代码里的、视频里的、同事口头说的都不算数。
5.2 静默截断：上下文窗口超限
另一个隐蔽的问题发生在上下文管理上。某一天我让 HagiCode 分析一个大型前端项目，它传入的上下文超过了 GLM 模型的窗口上限。让我意外的是，API 没有直接报错，而是静默地把最前面的内容截断了。这导致 Gemini CLI 那边同样的问题也存在——我在做跨文件重构时，它因为上下文里缺失了前几个文件的关键定义，生成了一个错误的接口签名。
问题的可怕之处在于：模型不会主动告诉你"我看不到前面的内容了"。它的回答依然自信，但隐含信息已经缺失。我是在审查它生成的代码时，发现某处引用了一个根本不存在的变量，才顺藤摸瓜找到根因。
由于 HagiCode 的模型配置里可以设置context_window上限，我把 GLM 的值设置为官方安全值以下，并开启上下文溢出监控。一旦单次会话注入量超过阈值的 80%，HagiCode 就默认启用"折叠历史"策略，把早期轮次的代码内容压缩成摘要，而不是直接截断。
5.3 Gemini CLI 登录态丢失与环境变量传递
Gemini CLI 集成最复杂的问题出在登录态。HagiCode 以子进程方式调用gemini-cli时，子进程不一定能继承 HagiCode 主进程的环境变量。如果 Gemini CLI 的认证凭证路径在另一个用户目录下，或者环境变量HOME没传对，子进程起来后就是一个未登录的状态，所有请求都会被认证错误拦死。
排查时我先在终端手动运行gemini-cli验证登录有效，然后才发现是 HagiCode 的进程环境里压根没有继承登录凭证相关的变量。解决方法是：在 HagiCode 的模型提供方配置里显式声明需要传递的环境变量白名单，或者干脆把 Gemini CLI 的认证凭证路径软链到 HagiCode 可访问的位置。这个问题做完之后，我把排查步骤写成了一个小脚本，万一再出现认证报错，一键就能定位到是环境变量问题还是凭证过期问题。
5.4 Tool calling 格式不兼容：同一套代码不能两边通吃
这是最烧脑的一个问题。HagiCode 有一套内部定义的工具描述格式，在调 GLM 时能顺利转化成 OpenAI 风格的工具声明；但同样的描述转到 Gemini CLI 那边，工具名和参数格式对不上。
具体症状是：Gemini CLI 侧的 Agent 收到工具定义后，要么完全无视，要么把参数格式理解错误，导致工具执行失败。由于 Gemini CLI 有自己的工具编排体系，当 HagiCode 把工具描述按照自己的格式传给它时，两边需要对参数做一次"翻译"。这个翻译如果只做表面映射，深层嵌套结构就会出问题。
我的解决思路比较务实：不让 HagiCode 把内部工具强塞给 Gemini CLI，而是让 Gemini CLI 保留自己的工具调用习惯。HagiCode 只负责把用户意图转达给 Gemini CLI，至于它内部怎么调用工具、怎么编辑文件，完全放给它自己决定。换句话说，让两边各用自己的母语，而不是强行统一语言。
这也揭示了一个深层的产品理念：当你把一个 Agent 工具（比如 Gemini CLI）集成到另一个宿主工具（比如 HagiCode）里时，不要试图控制对方的内部行为细节。你只能管住边界，管不住内部。管住边界，双方互不干扰就万事大吉。
5.5 限流与重试：并发过多时的不稳定
多模型接入后，我兴奋地把 HagiCode 里所有自动化任务都配上了相应模型，结果某天多个任务并发触发，GLM 接口开始零星返回限流错误。当时第一反应是质疑 API 稳定性，后来查到原因其实很朴素——忘记给模型提供方单独设置并发上限，HagiCode 默认放开了并发限制，导致同一个密钥的请求量瞬间打到了服务商阈值。
现在我会在模型配置里显式限定单模型的最大并发数：
zhipu: max_concurrency: 8 retry_interval: 1.5 max_retries: 3同时给重试加上了指数退避策略。浪费了整整一个下午的调试时间换来的收获是：任何第三方 API 都不是无限吞吐的，本地工具的并发控制不能靠"服务商应该足够强大"这种一厢情愿的想法。
6. 下一步的进化方向：把多模型变成 Agile 的工具链，而不是一堆按钮
接入 GLM 并集成 Gemini CLI 之后，HagiCode 在我这已经从一个"单模型编辑器增强工具"变成了一个真正的多模型工作台。但工具接入只是第一步，更值得投入的方向是如何让多个模型像团队一样协作。
我现在正在实验的思路是：给 HagiCode 设计一个工作流声明文件，用 YAML 描述一个任务的完整流水线。比如一个大型重构任务，可以拆成四步：第一步 GLM 负责扫描代码结构并生成文件清单；第二步 Gemini CLI 负责输出重构方案；第三步回到 GLM 快速审查方案中的低级错误；第四步再由 Gemini CLI 执行具体修改。每步之间通过文件系统传递中期产物，不共用对话上下文。
这个思路跑通后，多模型就不再是"几个可切换的后端"，而是一个有分工、有接力、有背书的工程流水线。当然，流水线化也带来了新的调试难度，任务一旦卡在某一步，定位问题要比单模型复杂得多。所以我在实验时很注意每一步都记录输入输出摘要，确保可回溯。
另外，我也在关注智谱平台上的新模型迭代，尤其是更强推理能力的大杯型号。如果 HagiCode 后续能针对 GLM 的函数调用格式做更深度的优化，让工具参数支持嵌套结构，那 Agent 类任务的整体完成度还能再上一个台阶。
最后分享一个我个人的习惯：任何模型接入后的头两天，我只在低风险项目上用它，让它跑一些小任务积累运行数据。确认它和 HagiCode 的协作稳定之后，再逐步开放到主力项目。这个"观察期"看起来保守了一点，却帮我在多模型切换这件事上避免了 90% 的急性翻车。毕竟，工具是拿来用的，不是拿来供着的——稳定这两个字，比任何花哨的功能都值钱。
