HagiCode多模型调度实战：GLM与Gemini CLI无缝集成指南

HagiCode 最初在我电脑上只是一个用 Python 拼出来的脚本：让 Gemini CLI 的请求可以转发到不同模型后端。后来它越滚越大，GLM 正式接入后，多模型调度就成了这套工具最核心的能力。如果你也在做 AI Coding 工具或者 Agent 类命令行产品，正在纠结怎么把 GLM 和 Gemini CLI 同时集成进来又不把代码搞成一团浆糊，这篇应该能帮你省不少时间。

我会把这次改版里踩过的坑、做过的取舍、最后沉淀下来的调度结构都讲清楚，内容偏实操，你可以直接对照自己的项目改。

1. 为什么HagiCode要把GLM和Gemini CLI放进同一个调度层

1.1 单模型编码工具的“偏科”问题

先说背景。HagiCode 早期是绑定某一家模型 API 的终端助手，用来做代码补全、提交信息生成、还有简单的文件级重构。当时只有一个模型在后面跑，界面倒是简单，但用久了你会发现一个很现实的问题：没有哪个模型能同时在代码生成、长上下文分析、工具调用稳定性、成本这几个维度上全部拉满。

比如上一代主流模型在处理那种跨十几个文件的大重构时，经常前面上下文还很清醒，改到中后期就开始自说自话，把不相关的代码也给你改了。另一些模型代码补全质量不错，但让它老老实实调用工具函数，动不动就少传参数、多传假参数。Gemini CLI 给我的体验是 agentic 能力很强，会在终端里自主执行命令、读文件、跑测试，闭环完成度不错。但它的某些行为是黑盒的，不方便在项目里做细粒度的鉴权、统计和模型替换。

这个“偏科”问题不是靠调 prompt 能解决的。更麻烦的是，团队里不同人用同一套 HagiCode，有人觉得模型 A 顺手，有人觉得 B 更懂他们的老项目，如果不支持多模型，只能逼着所有人将就同一个选择。

1.2 多模型调度的真正价值：容灾、成本、场景分工

所以我做这次重构时，第一原则不是“多接几个模型显得厉害”，而是把“模型选择权”从代码里解放出来。这里说的多模型，至少包含三层含义。

第一层是容灾。实际开发中，上游 API 不稳定、限流、欠费、临时维护都是会发生的。过去单模型被限流，整个命令行工具就瘫了，体验很糟糕。支持多模型之后，我可以配置自动降级策略：主力模型返回 429 或者 5xx，自动把请求切到备用模型，用户感知到的只是慢了半拍，而不是中断。

第二层是成本。即便同为 GLM 系列，旗舰模型和轻量模型的价格差距也可以非常大。以前所有请求都塞给最贵的模型，月底账单出来吓一跳。接入多模型后，可以按任务类型拆分：简单的正则提取、代码格式化、提交信息生成，走轻量模型；复杂架构讨论、跨文件 bug 排查，再走旗舰模型。

第三层也是我理解最深的一层：质量偏好。不同模型对同一段代码的理解经常不一样。有些模型适合做第一遍草稿，有些模型更适合做评审纠错。如果只锁死一个模型，等于把这条链路的上限焊死了。把 GLM、Gemini 这类模型同时挂进来，让它们轮流处理、交叉验证，比单个模型反复自我检查要可靠得多。

1.3 这次重构最终确定的架构原则

HagiCode 现在的定位，不是一个“又一个套壳客户端”，而是一个模型调度层。它外面是 CLI 和 IDE 插件，中间有一套统一的请求上下文结构，底层通过不同的 provider adapter 接各家模型。

整个架构就四条原则：

• 用户的业务请求只描述“任务”，不绑定具体模型；
• 每个 provider 独立维护 key、base_url、模型列表和速率限制；
• 所有模型会话记录统一为中间格式，可以跨模型转移；
• 路由规则可配置，支持“按任务类型”“按成本”“按用户手动指定”三种模式。

这四条看着简单，真正落地时每一个都很折腾，尤其当你把 Gemini CLI 这种自带 agentic runtime 的东西接进来，情况会比调 API 复杂得多。后面重点讲我在这上面的处理方法。

2. GLM接入实操：从申请 key 到配置落地的完整路径

2.1 准备：API Key 和 GLM Coding Plan 体验卡怎么用

先说大家最关心的 key 获取问题。智谱 AI 开放平台注册之后，控制台里创建 API key，这一步没有任何门槛。有一点容易被忽略：同一个账号下可能有多个项目，API key 绑定的权限范围要看清，我只给 HagiCode 单独创建了一个专用 key，而不是拿主 key 到处用。这样万一哪台机器的环境变量泄了，直接在控制台吊销这一把就行，不影响其他业务。

GLM 官方在推广 Coding Plan 时经常送 7 天体验卡，这东西说白了就是给你一段时间的模型调用额度，让你把 GLM 接到自己的编程工作流里体验效果。体验卡怎么用，我见过的几种入口是：平台控制台的“资源包 / 权益兑换”页面，或者收到的活动链接里直接绑定。兑换后会变成额度或者套餐，出现在账户资产里。使用 HagiCode 接入时并不需要额外处理体验卡，它最终体现为账号下面的余额和限流策略，只要 API key 是同一个账号，请求就会自动走对应的权益。

这里提醒一句：体验卡通常有有效期和模型范围限制。有的卡只适用于特定模型，有的只限新用户。我建议兑换后立刻去模型广场或 API 文档页确认一下可用模型列表，别配置了半天，结果发现某个模型 ID 根本不在权益范围内。

2.2 协议选型：直接用 OpenAI 兼容接口，还是智谱原生 SDK

接到 GLM 的时候，我第一件事不是写代码，而是想清楚用哪种协议接。智谱 API 兼容 OpenAI 的 Chat Completions 风格，也有自己的原生 SDK。到底选哪个？

我的决定是：HagiCode 的 GLM adapter 主要走 OpenAI 兼容协议，特殊能力再单独透传。

原因很直接。Gemini CLI、HagiCode 的旧逻辑、还有一些内部脚本之前都已经兼容 OpenAI 的请求格式。GLM 如果也能走同一套格式，那我在抽象层不需要为它单独发明一套接口。request body 里 model 字段换成 GLM 的模型名，base_url 换掉，其余工具调用格式都是通用的。几十行代码就能把新模型接入现有的模型路由表。

原生 SDK 不是不好，但不利于做“多模型统一调度”。如果我给 GLM 用一套独立 SDK，给 Gemini 用另一套，那么上层就要写两套 error handling、两套流式解析、两套超时重试逻辑，维护成本立刻翻倍。而统一走 OpenAI 兼容协议之后，核心调度逻辑只需要维护一份。

有朋友可能会追问：GLM 的某些高级参数，OpenAI 兼容接口不支持怎么办？我的答案是：底层 adapter 保留一个 kwargs 透传通道。模型专属参数可以先放到一个独立字段里，请求发出去前再合并进 body。这是一个“80% 统一，20% 透传”的思路，兼顾整洁和灵活性。

下面是一段简化了的 adapter 初始化示例，配合 openai Python SDK 使用：

python复制from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4",
)

resp = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {"role": "user", "content": "检查 src/auth.py 里的登录逻辑"},
    ],
    tools=TOOL_SCHEMAS,
)

核心其实就两个参数：api_key 和 base_url。只要这两个对了，请求就能通。剩下的模型名、temperature、max_tokens 都跟其他模型大同小异。

2.3 HagiCode 里的模型配置模板参考

既然是多模型调度，配置管理就是基础设施。HagiCode 使用 YAML 文件集中管理所有 provider，大概结构如下：

yaml复制providers:
  - id: zhipu
    name: GLM
    type: openai_compatible
    api_base: https://open.bigmodel.cn/api/paas/v4
    api_key_env: ZHIPU_API_KEY
    timeout_seconds: 120
    models:
      - id: glm-5.3-flash
        role: cheap
        max_input_tokens: 128000
      - id: glm-4.6
        role: smart
        max_input_tokens: 200000
  - id: gemini_cli
    name: Gemini CLI
    type: gemini_cli_wrapper
    command: gemini
    api_key_env: GEMINI_API_KEY
    models:
      - id: gemini-2.5-pro
        role: smart
      - id: gemini-2.5-flash
        role: cheap

router:
  default_provider: glm-5.3-flash
  tasks:
    commit_message: glm-5.3-flash
    code_completion: glm-5.3-flash
    refactor_review: gemini-2.5-pro
    bug_analysis: gemini-2.5-pro
    api_docs: glm-4.6

api_key_env 字段只存环境变量名，不直接存 key。这是为了避免把密钥写进仓库。HagiCode 启动时会检查环境变量是否存在，不存在则给出明确提示，而不是让你去翻源代码找配错的地方。

models 列表里我用 role 字段标注了 cheap / smart，主要用于上层自动路由。type 字段告诉调度器：这个 provider 是普通的 HTTP API 类型，还是需要拉起外部 CLI 进程的 wrapper 类型。这一步区分很重要，因为它直接决定了后面“调用”“重试”“杀掉超时任务”等逻辑的写法。

2.4 让 GLM 真正干活：编码场景下的参数和工具定义

GLM 这块我调试下来，有几个值得记录的参数经验。

第一个是 temperature。写代码这种场景，我不建议调太高。默认 0.2 到 0.4 之间比较稳，太高容易产生幻觉式的“创新”，给出不存在的函数名。如果做头脑风暴设计，才考虑调到 0.7 以上。HagiCode 里的做法是给不同的 tool call 预设不同的温度，而不是全链路用同一个值。

第二个是 max_tokens。代码 Agent 经常需要输出很长一段完整文件，如果输出截断在中间，修复起来比不生成还痛苦。我会把代码生成类任务的 max_tokens 设到模型允许的上限，哪怕有时候实际不需要那么长，也好过生成一半被截断。

第三个是 tools 定义。GLM 对工具调用的支持已经很稳定，但工具描述要写准确。不要写“调用这个函数修复代码”这种模糊描述，而应该写清楚什么时候调用、需要哪些必填参数、每个参数的单位和取值范围。模糊的描述会导致模型乱传参数。我其中一个工具函数定义如下：

json复制{
  "name": "apply_patch_to_file",
  "description": "对指定文件应用一个代码补丁。仅当用户要求修改代码时调用。",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {"type": "string", "description": "需要修改的文件的绝对路径"},
      "patch": {"type": "string", "description": "符合 unified diff 格式的补丁内容"}
    },
    "required": ["path", "patch"]
  }
}

这些经验单独看都是小细节，但串起来之后，GLM 在 HagiCode 里的完成度会从“偶尔能用”变成“稳定靠谱”。

3. Gemini CLI集成和GLM的配合方式

3.1 Gemini CLI 的交互逻辑有什么不同

Gemini CLI 不是一个简单的 HTTP API 封装，它本身就是一个完整的 agentic 编码客户端。启动它之后，它会在终端里规划任务、列出待办步骤、执行命令、读取文件、调用外部工具，并且用户可以随时介入修改方案。

这种交互模式很棒，但给集成方带来的问题是：你不能像调普通 API 一样只发一个 POST 请求就拿到完整结果。Gemini CLI 会在自己的进程内维护大量状态，包括工作目录、修改历史、工具调用记录、用户确认过的上下文。外部程序想和它“集成”，本质上是在和它的进程和输出流打交道。

HagiCode 最初只是简单地调用 Gemini CLI，但很快就发现两个问题：第一，无法获取结构化的多轮记录；第二，无法在 Gemini CLI 之外插入 GLM 这种替代模型实现无缝切换。用户想让 Gemini 跑一遍初稿，再让 GLM 复查一遍，就得手动复制粘贴上下文，非常蠢。

3.2 让 GLM 和 Gemini CLI 协同：不争夺话事权，而是分工

所以这次升级我把集成方案重新拆了一遍：Gemini CLI 继续保留自己的 agentic 主循环，但它产生的所有中间信息都会同步到 HagiCode 的上下文存储里；GLM 则作为另一个 provider 被挂在同一个上下文存储上。简单说，HagiCode 不尝试成为“第二个 agent”，而是成为“agent 之间的转接口”。

实际效果是，用户可以给一个任务指定“先由 Gemini CLI 执行重构，重构完成后调用 GLM 对最终代码做评审”。Gemini 跑自己的工具链，GLM 只负责审，双方不用抢同一个工作目录，也不会互相打断。

这套分工模型出自一个很朴素的原则：不要让两个 agent 同时改同一份文件。我在早期实验时，让两个模型在同一目录下并行修改，结果既不产生合并冲突，偶尔还会互相覆盖对方的补丁。后来改成严格的串行协作，再引入“评审者不直接改代码，只输出 review comment”的机制，稳定很多。

3.3 路由策略与实现细节

路由规则我分成了三层，优先级从高到低分别是：

1. 手动指定：用户命令里直接 model=glm 或者 model=gemini，无论配置规则是什么，都听用户的。
2. 任务类型匹配：router 根据任务描述里命中的关键词，选择对应模型。
3. 默认默认：如果上面都没命中，就落到 router.default_provider。

任务类型匹配依赖的是一组关键词规则。比如 commit_message 会匹配“提交信息”“git commit”“commit message”；bug_analysis 会匹配“报错”“崩溃”“排查”“NPE”等。这里不建议搞太复杂，规则多了反而误命中。

在实现层，有一个点很关键：GLM 这种普通 HTTP provider 失败时可以立刻重试，但 Gemini CLI 这种 wrapper 类型绝不能盲目重试。因为 CLI 进程可能已经改了本地文件，重试它可能会把上次未完成的操作又叠一遍。我为它们设计了不同的失败策略：HTTP 型 provider 支持 3 次指数退避重试；CLI 型 provider 失败后只记录日志，并提示用户介入确认当前工作区状态。

另外，上下文同步是我花时间最多的部分。你可以把它理解成一份标准化的“会话快照”。无论是 GLM 还是 Gemini CLI，各自的输入输出都转换成同一个 message 格式，存进一个 SQLite 会话库。这样做的直接好处是，用户可以在同一个会话里先让 GLM 快速生成一个原型，再把整个会话快照交给 Gemini CLI 继续完善，两个模型面对的是同一批历史往来。

简化后的伪代码大概是：

python复制session = Session.load(session_id)

messages = session.to_openai_messages()
glm_review = glm_chat.complete(messages, model="glm-4.6")

session.add_message("assistant", glm_review)
session.export_for_cli("gemini_cli")

真实场景里肯定有各种字段转换的糟心事，但方向走通后，体验会非常顺滑。

4. 混合链路跑通：从安装配置到真实修复任务

4.1 初始化 HagiCode 并添加 GLM provider

按我上面说的结构，如果你也打算在自己工具里做相似集成，参考流程可以是这样的。先打开终端，准备一个干净的 Python 3.11+ 环境：

bash复制pip install hagicore
hagicode init
hagicode provider add zhipu \
  --type openai_compatible \
  --base-url https://open.bigmodel.cn/api/paas/v4 \
  --api-key-env ZHIPU_API_KEY

hagicode init 会在用户配置目录生成 config.yaml 和 SQLite 会话库。provider add 的作用只是把 provider 信息写入配置，不会去测连通性。验证要单独做：

bash复制export ZHIPU_API_KEY=你的key
hagicode test zhipu --model glm-5.3-flash

跑通之后，HagiCode 会自动拉取该模型的上下文长度，写入配置缓存，方便后面的路由判断——短模型就不要硬塞一个超长文档进去。

Gemini CLI 这一侧不需要额外安装，HagiCode 在配置文件里记录其可执行文件的路径。每次调用时优先使用当前激活的环境变量作为鉴权，如果需要切换不同账号，可以指定 --profile。

4.2 用一个真实 bug 修复过程做验证

光说理论没用，我拿一个非常典型的现场任务演示：用户报告登录接口偶尔报 500，原因是并发情况下 session 失效。这类问题在单模型时代会很依赖模型的经验，模型见过多少类似代码，直接影响排查速度。HagiCode 的处理流程改成：

第一步，路由判定。任务描述命中 bug_analysis，自动落到 gemini-2.5-pro。

第二步，HagiCode 启动 Gemini CLI 进程，工作目录设置为项目仓库。Gemini CLI 读代码、复现步骤、最终定位到一处竞态条件，并给出了修复补丁，全程十几秒。

第三步，HagiCode 自动把这十几秒里的多轮交互记录统一存入会话库，然后把修复后的最终 diff 连同原问题描述一起发给 GLM 做代码评审。GLM 输出的评审意见不是“看起来没问题”，而是明确指出补丁里少处理了另一种异常分支。

实际执行输出大概是这样的：

text复制[info] router: task=bug_analysis -> gemini-2.5-pro
[agent] gemini-cli: running with workspace=/data/app
[agent] gemini-cli: read src/session.py
[agent] gemini-cli: reproduced error in test_login_race
[agent] gemini-cli: proposed fix in src/session.py
[info] context manager: session saved, id=2f3a
[info] router: task=code_review -> glm-4.6
[agent] glm-4.6: review p1, potential unhandled branch
[info] review_count=1 suggestions=2

这不是一个炫技的 demo，而是我在真实项目里反复跑了很多遍的流程。双模型协作下，bug 定位和代码审查各交给擅长的一方，输出质量明显比我以前只叫一个模型连续干两轮要高。

4.3 成本和多模型切换的实际数据

我把一次典型接入改造的测试成本记录分享一下。测试任务是同一个仓库里的 5 个中级 bug，用三种配置跑：单 Gemini 旗舰、单 GLM、混合路由。

表格如下：

费用只是相对比较，不同时期各家定价经常调整，具体金额参考意义有限。但这个数据说明一点：混合路由不意味着质量打折。因为工具调用、无效生成、重试次数都有下降，总 token 未必更高，费用反而被压制了。

多模型最大的成本收益来自“把旗舰模型的请求量降下来”。简单任务丢给低价模型，旗舰只在复杂分析阶段参与，这是最直接、效果最明显的省钱策略，比去各大模型之间比单次 token 单价更有意义。

5. 常见问题与排查技巧实录

5.1 GLM API 返回 401 或 429，先查 Key 再查余额再查限流

GLM 接入最常碰到的错误就是鉴权和限流。401 时优先检查环境变量名字有没有拼错，确认 key 是不是当前生效的 key。我见过太多次：配置文件没问题，但 shell 里的 export 只在当前窗口生效，换个终端窗口就变成旧 key。

429 常见于两类情况：一是真的超过了账号的 RPM/TPM 限额，二是余额耗尽了。智谱在余额不足时返回的具体错误码可能因接口版本而异，我的经验是先把错误响应全文打出来看一眼，很多问题从 message 里就能看到明确提示，而不是一头扎进代码里查。

5.2 Gemini CLI 与 GLM 之间最容易出现的“会话串号”

这部分我要重点提醒。当你在同一个 shell 里同时设置了多个模型的 key，且 HagiCode 使用命令行环境变量作为鉴权来源时，有一个非常隐蔽的 bug：某些子进程会继承父进程的环境变量，导致 GLM 的 provider 发起请求时误用了其它模型的 key，或者 Gemini CLI 启动时带上了 ZHIPU_API_KEY。请求可能发送成功，但因为 key 不对应，平台会拒绝或者把费用记到别的账号里，非常难排查。

我最终的解决办法是：每个 provider 子进程在启动前清理相关环境变量，只保留自己需要的那些；核心进程统一从一个加密存储里读取 key，不再依赖外部 shell 环境变量。HagiCode 里也加了一个 debug 命令，可以直接打印某个 provider 实际会用到的 key 前缀和 base_url，避免靠猜。

5.3 长上下文跨模型切换导致上下文截断怎么办

还有一个高频坑是长文档跨模型切换后被截断。GLM 和 Gemini 的上下文窗口不同，同一个会话快照在模型 A 那里能装下，切到模型 B 之后可能超过其长度限制。如果你不做处理，模型 B 不会告诉你说“你的上下文太长了”，它可能直接丢掉中间部分，结果明显答非所问。

HagiCode 的做法是给每个 provider 模型都配置一个 max_input_tokens，在切换前先做一次 token 估算。如果超限，自动执行摘要压缩：把早期轮次的一般性对话压缩成 summary，尽可能保留代码 diff 和关键结论。如果还是超，就明确报错提示用户换更长的模型，而不是悄悄截断让用户对结果产生误判。

还有一个容易忽略的体验问题：CLI 工具输出中文/英文时使用不同编码，在 Windows 终端里经常看到乱码。HagiCode 现在会在初始化时检测终端编码，明确强制输出 UTF-8，并且把进程标准输出和标准错误流做统一解码。这个问题不解决，GLM 输出一长段中文注释时很容易出现半截乱码，但那并不是模型的问题，而是管道编码问题。

6. 经验心得：多模型集成的三步走

6.1 先统一会话格式，再接新模型

这次演进让我体会最深的是：不要第一个动作就去把 GLM 的 SDK 拉进来写调用，先把“会话历史”“工具调用记录”“输出格式”这层中间抽象稳定住。HagiCode 能在一周内就完成 GLM 接入，一个重要原因就是模型无关的中间层已经写好了，新模型只是换一个 adapter。

后面的工具里还会支持更多模型，我可以预见到，需要处理的模型专属能力会越来越多：有的模型视频理解更强，有的模型支持某些特殊工具结果注入。遇到这些“一个模型有而另一个没有”的特性时，策略还是那两个字：透传。在协议层给每个 provider 留一个“扩展配置区”，不加进核心数据结构里。核心数据保持精简，模型差异在 adapter 层消化掉。

6.2 路由规则要能从配置文件里随时调整

团队使用工具，需求一定会变。今天大家觉得“所有复杂问题都要走旗舰模型”，明天可能成本压力上来，又想把一部分任务切到便宜模型。如果模型路由是写死在代码里的，每次调整都要重新改代码发版，那基本等于没有多模型能力。把路由规则外置到配置文件，让普通用户也能直接改，这是工具能持续被用起来的分水岭。

6.3 不迷信模型，只衡量“完成度”

最后说点虚的。现在模型更新迭代极快，既有 GLM 的连续更新，也有 Gemini 等各家产品不断推新。与其纠结某个版本号或者某个榜单分数，不如把评价标准固定成几个实际问题：它能不能稳定调用工具，能不能在长上下文里不丢指令，能不能在你项目里解决真实的 bug，成本是不是你能接受。

HagiCode 从 Gemini CLI 单链路走到 GLM 等多模型接入，带给我的最大改变不是“能调更多模型了”，而是代码仓库的架构终于不再被某一家模型绑定。这种选择权握在自己手里的感觉，在实际运维和日常开发里是最值钱的。后面我会持续在这套工具上做更多 provider 适配，到时候再回来分享新踩的坑。