HagiCode：统一调度GLM与Gemini CLI的多模型终端工作流

GLM 和 Gemini CLI 这两个名字放到一起，乍看像是“又要折腾一遍配置”，这也是我一直头疼的地方。终端里做编码 Agent 的 CLI 越来越多，各有各的模型默认值、各有各的环境变量和工具调用格式，真正跑起来之后并不是多模型“随便切换”，而是多模型“一家一个生态”。HagiCode 这个项目就是我从这种混乱里抽出来的解决方案：它不重新发明一个 Coding Agent，而是做一层很薄的调度和适配，让 GLM、Gemini CLI 这些后端可以按任务、按成本、按稳定性需求被同一个入口调用。这轮更新里最核心的一件事，是把 GLM 接成了“全面支持”，不是简单发一个 HTTP 请求能通，而是把工具调用、流式解析、上下文回传这些环节都对齐了，让我可以安心地把 GLM 和 Gemini CLI 放在同一条流水线上跑而不需要写两套胶水代码。

这篇就拆开聊聊：HagiCode 为什么要做多模型后端，GLM 接入过程中真正难处理的点在哪，以及一个普通开发者如果也想在自用工具里搭一套“GLM + Gemini CLI 共存”的 CLI 工作流，应该怎么做、会踩到什么坑。

1. HagiCode 的定位是“调度层”，不是为了替代 Gemini CLI

1.1 从 Gemini CLI 说起：单后端的痛点

我很早就把自己的日常编码任务托付给 Gemini CLI，看中的是它的 Agent 工作流相当完整。你给它一个 Issue 或者一个含糊的“把登录模块抽出来重构一下”，它会自己读目录、跑测试、改文件，再回过来给你解释。这种东西一旦用顺了，大部分人就不会再折腾别的 CLI。

可问题也在“一旦用顺了”这四个字上。单一后端意味着你被绑定在一个模型体验里。项目里有些任务量不大，就改两行配置，用大模型跑太浪费；有些任务是长链路重构，可能要好几个小时，会频繁碰到限流；还有些任务是中文文档整理、老代码加注释，不同模型的理解偏差很大。这些都不是 Gemini CLI 本身出了问题，而是“一个 CLI 只对一个模型”这种架构的天然短板。

我一度在终端里同时打开好几个会话框，Gemini CLI 开一个窗口，另外再开一个别的模型终端，遇到不同任务切过去。一来窗口管理很乱，二来每个工具的 prompt 习惯、工具前缀、环境变量都不一样，切过去了也很难达到同一套操作手感。HagiCode 最早的动机就来自这里——我需要的不是“再多一个 CLI”，而是“一个能指挥不同 CLI 的入口”。

1.2 HagiCode 做成什么形态

HagiCode 在设计上刻意保持“薄”。它不做重 UI，不在 IDE 里抢占快捷键，也不自己写一个代码编辑器。它做的事情，简单说就是三件：

• 维护模型提供商列表和各自的认证信息；
• 把用户的一句话任务通过适配层转换成对应模型能理解的 Agent 请求；
• 把不同模型的流式输出、工具调用、拦截确认统一回调到同一个终端交互界面里。

配合 Gemini CLI 使用时，有两种典型姿势。一种是把 Gemini CLI 当作后端执行器，HagiCode 解析完任务后把子任务交给 Gemini CLI 的命令行模式；另一种是 HagiCode 直接以 Gemini 的模型 API 为后端，走一套更可控的 Agent 循环。两种模式在配置层只需要切换一行 adapter 类型，这也是为什么要做多模型支持的原因——模型的差异应该被封装在适配器内部，而不是暴露到日常命令里。

很多朋友听到这第一反应是：“这不就是套了个壳吗？”确实，外壳这个词没有说错。但壳和壳之间最大的差别在于：它是不是真正用统一的内部消息结构去接住了不同模型的差异。如果只是把 key 存在一个配置文件里，那叫环境变量管理，不是多模型接入。HagiCode 的价值点在于 Agent 循环消息的归一化，这个在第三节里展开讲。

1.3 多模型中“怎么选”比“哪个好”更重要

这次把 GLM 加进来以后，我用的策略不是“用 GLM 替代 Gemini”，而是给不同任务画了不同的路由。比如：

• 日常小改动、脚本修正、接口文档生成：默认走 GLM，成本低、中文表达也更顺；
• 跨目录重构、老项目梳理、需要长上下文跟踪的问题：走 Gemini CLI，长上下文的稳定性和工具连续调用表现更让人放心；
• 两个模型并行跑同一任务的对比模式：拿 HagiCode 的 pair 参数一次性拉起两个后端，分别给出修改方案，再人工比较。

这个表不是想证明 GLM 和 Gemini 谁碾压谁，而是在真实工程里，你根本没有必要让一个模型承担所有类型的任务。模型能力迭代非常快，今天合适的判断，可能下个版本就不合适。HagiCode 的多模型架构，本质上是一种“不要把鸡蛋放在同一个模型篮子里”的策略。

提示：多模型路由不是把任务随机分发，而是要先给任务分类。前期可以先用简单的关键词路由，比如带“测试”“重构”“文档”的任务分别走不同后端。跑一阵子再根据真实反馈调优。

2. GLM 接入：兼容接口之上，还有四道需要处理的坎

2.1 兼容接口只能保证“能连通”，不能保证“能干活”

GLM 这边在接口兼容上做得不错，基本上主流 Coding Agent 常用的那套协议它都提供了兼容端点。也就是说，理论上你把 HagiCode 的 base_url 一改、key 一填，请求就能发出去。

但我调试的第一天就发现，“请求通了”和“Agent 能像 Gemini CLI 那样稳定工作”完全是两码事。Agent 是一个循环：模型返回一个动作，CLI 执行动作，把结果拼回消息历史，再送回去让模型决策下一步。这个循环里任何一个环节格式不兼容，都会让模型产生错误动作，最典型的就是反复重试同一个函数、或者干脆退出循环告诉你“我已经做完了”但其实根本没执行。

举个例子，GLM 走的兼容接口如果用的是 Anthropic Messages 那套结构，那么工具调用会包装在 tool_use 块里，而后端返回给 Agent 的中间执行结果需要包装成 tool_result 块。看起来很简单，真实请求里还会夹杂模型输出的思考内容、系统指令、多轮工具结果。每一个字段的顺序、角色、内容格式都必须严格对齐，否则整套 Agent 循环直接断层。

所以我把“全面支持”定义为四个硬性条件：

• 单轮对话返回正常；
• 多轮上下文能记住之前操作；
• 工具/函数调用能连续执行并正确回填；
• 长任务中断或出现异常时有可恢复手段。

四步全跑通，才算是一个可以日常使用的后端，而不是只能拿来聊天和提问。

2.2 思维链字段：最容易出问题但最容易被忽略

不同模型在输出答案时会先把推理过程“想”完再输出。GLM 这类模型在返回内容中有时会带专门的思考字段。这个字段从产品角度看是增强可解释性的，但从 Agent 循环角度看却可能变成灾难。

原因很直接：思考字段内容不应该被当成实际回答回传给历史，否则下一次请求时模型会看到一段“它自己刚才思考过程”的副本，干扰后续决策。在 Anthropic 兼容的消息结构里，如果上一条助手消息里带了思考块，下一条消息又带一版思考块，模型很容易在几轮之后开始输出重复的思考、忘记自己已经做过的工具调用。

HagiCode 的适配层在处理 GLM 返回时，会把两类内容分开。一部分是纯粹的思考过程，只进入内部日志，不进入历史上下文；另一部分是最终回答内容，进入上下文。如果模型返回消息里同时带了工具调用，则工具调用必须原样保留，不能因为剥离思考字段而丢失。

python复制# 示意逻辑：剥离思维链时，保留工具调用
def normalize_assistant_message(raw: dict) -> dict:
    content = []
    thinking = raw.get("reasoning_content") or raw.get("thinking")

    if thinking:
        # 思考内容仅记录到本地日志，不喂回给下一次模型请求
        logger.debug("reasoning from GLM: %s", thinking[:200])

    for block in raw.get("content", []):
        if isinstance(block, dict):
            # tool_use / tool_result 这种功能块必须原样保留
            if block.get("type") in ("tool_use", "tool_result", "text"):
                content.append(block)
        else:
            content.append({"type": "text", "text": str(block)})

    return {"role": raw["role"], "content": content}

这段逻辑看起来简单，实际上我前两个版本都漏掉了这个字段。结果就是模型在连续工具调用过程中开始“自言自话”，把中间过程当作最终结论，一个简单任务跑出大量无效 token。所以后面凡是接新模型，第一件事就是打开 DEBUG 日志看返回结构里有没有非标准字段，并且做好剥离处理。

2.3 工具循环：模型要有“自知何时停止”

工具调用是另一个大坑。前面说的是返回里的工具块保留问题，这里说的是模型对工具执行结果的反应问题。GLM 在单轮函数调用上表现不差，你给它定义一个查询函数，它知道什么时候该调用。但放在 Agent 场景里，我们需要它连续判断：

• 当前信息是不是已经足够改代码；
• 上一条命令执行失败了，是应该换一个命令还是直接修正文件；
• 改动完成后，是不是该跑测试来验证；
• 该结束任务时，是不是能主动停下并把改动总结出来。

HagiCode 里为此设计了一个 max_steps 的概念。一个任务最多允许模型连续做多少次工具调用，超过以后强制停止并要求模型用已有信息给出总结。这个参数在 GLM 后端我一般会调得比 Gemini 稍微小一点，因为实测在某些长任务里，GLM 会因为已经执行过多个工具后，仍然尝试再次调用只读命令来“确认”结果。这不是模型能力不行，而是 Agent 场景的“停止判断”本身需要额外约束。

另一个细节是并行工具调用。部分后端支持模型一次返回多个工具调用，GLM 的兼容模式下也会出现多个工具块。适配的时候必须决定是并行执行它们，还是串行执行。经验上是串行更不容易出错，因为编码任务里很多工具是有依赖的，比如先改文件再跑测试，这两者不能并行。HagiCode 默认把所有工具调用排成队列，逐个执行，只有标记了 parallelizable=true 的只读命令才会并行。

2.4 上下文的“长”和“长”不一样

Gemini 历来主打长上下文，GLM 也一直在这方面跟进。但实际体验里“支持多少 token”和“能在长上下文里不跑偏”是两个指标。我通常会用同一个任务去测试新后端：把一个有 50 个文件的模块目录丢给它，要求找出三处与某接口相关的调用并修改。

GLM 在上下文窗口内对早期文件的“记忆”总体是准确的，但如果早期文件和后边代码存在强关联，它会偶尔只按后面的代码片段判断，忽略前面埋下的线索。这种问题在 Gemini 上相对少一些，这也是为什么我把长链路重构任务默认路由到 Gemini。可反过来，GLM 对中文注释代码的改写、旧项目里的技术债说明，读起来比 Gemini 更贴需求，不用我再修一遍措辞。

所以后端选择不是只看参数表里写的支持窗口长度，更要看你任务里需要它“记住的原因链有多长”。如果任务是“改一个独立小模块”，短上下文后端完全没问题；如果任务是“先读 A，再根据 A 的结论去改 B，B 改了之后 C 的表现又会变”，这种需要模型在长链路里反复回溯早期结论，就需要对长上下文更稳定的后端。

3. 实测 GLM 与 Gemini CLI 共存的完整配置过程

3.1 安装与基础初始化

HagiCode 的安装比较常规，把它当普通命令行工具装好后，先执行一次初始化，生成工作目录和默认配置文件：

bash复制hagi init --workdir ~/.config/hagi

初始化之后，~/.config/hagi 下会生成 providers.toml 和 routes.toml。providers.toml 保存各后端连接信息，routes.toml 决定任务关键词/模式走哪个后端。这样的分离是为了让连接信息只属于本机，而路由规则可以跟随项目走。

这一步没什么特别的，顺着做即可。真正的配置工作在 providers.toml 里。

3.2 在 providers.toml 中同时配置 GLM 与 Gemini CLI

以我当前使用的版本为例，配置文件的框架大致如下：

toml复制# providers.toml
[provider.gemini-cli]
type = "gemini"
model = "gemini-2.5-pro"
auth_env = "GEMINI_API_KEY"

# GLM 走 Anthropic 兼容端点
[provider.glm]
type = "anthropic-compatible"
base_url = "https://your-glm-endpoint.example.com/anthropic"
model = "glm-4.6"
auth_env = "GLM_API_KEY"
timeout = 120
max_steps = 30

# 平时开发用的小规模任务后端
[provider.glm-fast]
type = "anthropic-compatible"
base_url = "https://your-glm-endpoint.example.com/anthropic"
model = "glm-4.5-flash"
auth_env = "GLM_API_KEY"
timeout = 30
max_steps = 10

这里有几个值得注意的地方。auth_env 指的是从环境变量里读取 API Key，而不是把 key 明文写在配置文件里。Gemini CLI 那边如果你已经在用官方工具，大概率已经设置过 GEMINI_API_KEY，HagiCode 直接复用它就行。GLM 这边我建议单独定义一个 GLM_API_KEY，因为不同服务的额度、计费、试用范围是分开的，不建议混用同一个 key 的环境变量名称。

glm-fast 这么一个小条目是我后来加的。它用更小的模型、更短的超时、更少的步骤上限，专门承接“帮我解释这个报错”“把这段脚本改短一点”这类轻量任务。多模型配置的意义就在于，你完全可以把同一家服务拆成多个后端配置，用同一个 API Key，但用不同参数和模型名，这样路由的时候就不需要额外传一堆参数。

3.3 设置 API Key 并验证连接

配置完成后，在运行任何任务之前先设置环境变量。终端里直接导出的方式最简单：

bash复制export GLM_API_KEY="你的 GLM API Key"
export GEMINI_API_KEY="你的 Gemini API Key"

这里有一条经验：如果是在公司电脑上，建议把这两行写进 shell 的 profile 文件或使用系统级密钥管理工具，而不是写进项目里任何 .env 文件。一旦 .env 被误提交到 Git，比写死在代码里还危险，因为很多自动化扫描工具会直接把 GitHub 上的密钥抓走。 HagiCode 本身不会启动时主动检查 key 是否存在，要等真实请求发出来才会报鉴权失败。所以配置完成后，建议先跑一个轻量任务而不是直接加载整个仓库：

bash复制hagi exec --provider glm "一句话说明当前目录结构和主要模块职责，不要读取代码细节"

如果这个任务能正常流式输出，说明 GLM 端点的连接和基础的流式解析都没问题。接着再跑一个需要真实工具调用的任务：

bash复制hagi exec --provider glm "看看当前目录下哪个文件引用了 Logger 类，用 grep 找到它并返回所在行号"

注意，这个任务并不要求模型真的有“编写代码”能力，而是在验证两件事：一是模型有没有正确发起 grep 之类的工具调用，二是执行结果是否正确拼回上下文。只有这一步通过，才说明 Agent 循环里的工具调用链路是通的。

3.4 用 pair 模式同时调用 GLM 和 Gemini CLI 做方案对比

HagiCode 里比较有意思的是 pair 子命令。它允许你在同一个任务上同时拉两个后端，并把两者输出都展示出来。我在接入 GLM 后的第一周几乎天天用这个模式。

bash复制hagi pair \
  --model-a glm:glm-4.6 \
  --model-b gemini-cli:gemini-2.5-pro \
  --task "阅读 docs/design.md，给出该模块拆分为独立服务时的影响面清单"

这里传入的 glm:glm-4.6 是“提供商名:模型名”的组合，HagiCode 会自动去 providers.toml 里找到对应配置。输出时左侧是 GLM 的分析，右侧是 Gemini CLI 的分析，两个流式输出相互独立，不会出现互相打断的情况。

这种对比有两个收获。第一是你能在真实项目上看到两个模型对同一任务的关注点差异，而不是对着公开榜单猜。第二是它能倒逼你把任务描述写得更精确。实测同一个任务，如果描述含糊，两个模型给出的影响面可能完全对不上；一旦把约束写清楚，两边都能给出更有价值的回答。后来我在 routes.toml 里把“方案设计类”任务默认配置成 pair 模式，把两个模型的分析合并到最终报告里，宁可多花点 token，也要避免单模型漏掉重要影响点。

3.5 把默认路由规则写进项目

配置后端是一回事，让多模型在日常使用中真正跑起来，还是要靠路由规则。HagiCode 的路由规则支持简单的关键词匹配，也支持按目录匹配。

toml复制# routes.toml
[route.default]
provider = "glm-fast"

[route.by-pattern]
patterns = [
  { match = "重构|迁移|影响面|依赖分析", provider = "gemini-cli", model = "gemini-2.5-pro" },
  { match = "注释|文档|README|单元测试", provider = "glm", model = "glm-4.6" },
]

[route.by-directory]
"legacy-module/" = { provider = "glm", model = "glm-4.6" }

我一般把低成本后端作为默认，因为日常终端里大部分问题是“帮我解释一下”“这个警告怎么回事”，不需要重型模型。只有遇到明确的重构、迁移、分析任务才切到更稳的长上下文后端。这种方式能够避免模型能力被浪费在琐碎请求上，也让费用控制在合理范围内。

注意：关键词路由只是起手式。真正好用的路由规则通常需要结合目录和项目类型判断，比如传统 Java 项目的 src/main/java 里经常有大量跨类调用，这种任务对上下文长度要求更高。写路由规则时不要贪多，先弄两三条常用的，跑一周再慢慢调。

4. 踩坑实录与问题排查表

4.1 最坑的不是模型本身，是消息历史回传

接入 GLM 的第一晚，我有一个反复出现的现象：模型在连续两轮工具调用后，开始循环调用同一个 list_files 命令，每次执行结果都一样，但它就是不推进下一步。一开始以为是模型提示词问题，加了“请直接继续”的约束也没改善。后来看 HagiCode 的 DEBUG 日志才发现，问题出在消息历史里不小心把带思维链的完整内容回传了，模型每一次都会先“重新想想自己到底看到什么”，想完之后又觉得信息不足，于是再次调用读取命令。

这个问题前面在 2.2 里提过。这里我想给一个更明确的调试建议：接入任何新模型时，第一件事永远是开启完整消息日志，把每一次发给模型的 messages 数组原样落盘。不要只盯流式输出，因为流式输出只能看到“模型答了什么”，看不到“模型上一步是怎么被引导的”。很多 Agent 循环的怪异行为，病根都在回传历史里多了一个字段、少了一个 tool_result、或者消息顺序错位。

4.2 超时与重试策略不能照抄

不同后端对长时间流式请求的处理差异很大。Gemini 那边的流式连接相对稳定，HagiCode 默认的超时策略基本不用改。GLM 在跑长上下文任务时，如果连续多个工具调用之间间隔较长，某些网关侧的连接可能在代理层被断开。第一次踩到的时候，任务跑了大概 8 分钟，中间都是正常的流式输出，突然整个流中断了，HagiCode 报了一个“connection reset”。

解决思路不是简单把超时调到无限大。无限大的超时会让故障一直挂着，占用会话资源。真正要做的是分两类处理：一类是模型在思考阶段长时间没有产出任何数据，这类可以设一个空闲超时；另一类是流式输出一直有数据但迟迟没有结束，这类不能靠空闲超时，要设一个总时长上限。

HagiCode 的实际参数是 timeout 控制单次请求总时长，idle_timeout 控制无数据时间。GLM 后端我一般把 idle_timeout 设成 30 秒，timeout 设成 120 秒。如果任务规模很大，可以在任务开头用 --timeout 300 临时覆盖总时长，而不是在全局配置里把超时往上提。

4.3 GLM 接入常见问题速查表

这张表看着简单，每一条背后对应一个真实调试现场。如果你也在自建类似的适配层，建议按这个思路单独维护一份问题清单，遇到新问题就往里补。模型每年更新好几次，每次更新都可能带来新的兼容性问题，有清单能让你省掉大量重复排查时间。

4.4 关于模型名与版本更新的实战经验

模型名是接入过程中一个比较容易出低级错误的点。GLM 的服务端模型名并不是完全固定的，它会因为套餐类型、版本上线节奏、甚至接入通道不同而有差异。我最初看到别人教程里写了一个模型名，直接复制到配置里，结果接口返回“model not found”。后来才发现是教程写的模型 ID 对应的是旧的编码套餐，我当前账号里并没有这个模型的访问权。

这种问题没什么高级解法，唯一建议是接新服务时先去官方文档或控制台页面确认你账号能用的 model ID 列表，而不是相信任何第三方文章里的“默认配置”。另外，把模型名单独抽象成 model 字段而不是写死在代码里，也特别重要。一个编码套餐、一个基础对话套餐，它们能用的模型名可能相同，但上下文窗口和限流策略不同，最好把套餐也体现在 provider 名称中，比如 glm-coding、glm-chat，免得日后混淆。

5. 推动 GLM 与 Gemini CLI 在团队里共同落地的个人体会

绕了这么一大圈，还是想讲讲一个人在实际用的时候和一群人用的时候，对多模型集成的感受差别。个人场景下，你想在哪个任务里用哪个模型，完全自己说了算，路由规则写坏了也只影响你自己，马上改就行。一旦你想让身边的同事也把 GLM 和 Gemini CLI 纳进工作流，问题就变了：不是“哪个模型好”，而是“这套配置要足够简单，简单到别人不需要理解 Anthropic 兼容和 OpenAI 兼容的差别”。

我自己的做法是搭建一套“团队模板仓库”。仓库里只放路由规则和 provider 示例文件，不存任何密钥。同事拿到的第一版配置里，GLM 默认作为日常轻量任务后端，Gemini CLI 作为深度重构后端。同事只需要在各自机器上执行：

bash复制cp providers.example.toml providers.toml
export GLM_API_KEY=...
hagi doctor

hagi doctor 会逐个后端发一个极小请求，检查连通性、模型可用性、环境变量是否设置。这一步能帮团队省掉大量“为什么我这跑不通”的初始疑问。真正有价值的并不是某个模型特别聪明，而是团队里每个人都能用自己的账号和额度，在同一套交互模式下公平地对比两个后端，避免出现“我用 Gemini 写出来的代码到了你电脑上环境不同就崩了”这种问题。

最后再分享一个非常具体的经验。我在给 HagiCode 写 GLM 适配器时，最担心的一个问题是过度适配：为了兼容某个模型的某个临时性输出字段，写了很多 if 分支，结果模型一周后更新，那个字段消失了，代码里留下一堆永远走不到的分支。后来我给自己定了一条规矩：适配层里只处理两类事情，一类是协议要求的功能性字段，另一类是会导致 Agent 循环崩溃的异常字段。任何“锦上添花”的字段解析都放在日志层，而不是放在核心处理链上。

这套思路从 GLM 扩展到 Gemini CLI 也完全适用。模型之间的差异会永远存在，但适配层的复杂度不应该随着模型数量线性增长。把核心消息结构归一化，把边缘特性隔离到日志，把路由规则放到配置里，让模型本身去竞争各自擅长的场景，这才是多模型集成真正该有的样子。如果你也在自建类似的工具箱，希望这篇里的思路和坑能帮你少走一段弯路。