Open Interpreter 接入 GLM 全指南：Z.AI / Zhipu AI 提供商选择与原生 ZCode Harness 配置

导读

本文以 docs/zh/zai-glm.md（与英文版 docs/zai-glm.md 内容一致）为骨架，讲解如何在 Open Interpreter 中通过 Z.AI（全球平台） 与 Zhipu AI（智谱，中国区） 的 GLM 模型完成编码任务：既可以使用开箱即用的 OpenAI 兼容 Chat 提供商走通用代理界面，也可以启用项目原生实现的 zcode harness，在 Rust 运行时中复现 ZCode 形态的编码代理行为。读完本文，你将能正确区分四种内置提供商、配置 ~/.openinterpreter/config.toml 中的 Messages 兼容提供商、理解 Chat 与 ZCode 两条链路的本质差异，并学会排查 401/403、配额与模型缺失等典型问题。文中所有结论均可对照仓库源码与维护的提供商目录逐一验证。

提供商矩阵：一个账户四种选择

Open Interpreter 同时内置了面向 Z.AI 全球平台与 Zhipu AI（中国区） 的服务提供商。两者都提供"按量付费通用 API"与"Coding Plan 订阅"两类端点，组合起来共四种提供商：

账户或服务	提供商 ID	凭证环境变量	端点类型
Z.AI 按量付费 API	zai	ZAI_API_KEY	通用 OpenAI 兼容 Chat API
Z.AI GLM Coding Plan	zai-coding-plan	ZAI_API_KEY	Coding Plan 的 OpenAI 兼容 Chat API
Zhipu AI 按量付费 API	zhipuai	ZHIPU_API_KEY	通用 OpenAI 兼容 Chat API
Zhipu AI Coding Plan	zhipuai-coding-plan	ZHIPU_API_KEY	Coding Plan 的 OpenAI 兼容 Chat API

需要特别注意：Z.AI 官方文档将通用端点与 Coding Plan 端点分开计价。请仅在具备对应订阅资格时使用 zai-coding-plan / zhipuai-coding-plan；使用通用端点不会消耗 Coding Plan 配额，反之亦然。在依赖订阅配额运行工作流之前，务必确认你的客户端与使用场景符合 Z.AI 当前的 Coding Plan 使用政策（如是否允许自动化调用、并发限制等），避免因误用端点而产生意外的按量计费。

源码中的真实端点定义

上述四种提供商并非文档虚构，而是全部登记在仓库维护的提供商目录 codex-rs/model-provider-info/provider_catalog.json 中，可通过其 id 字段逐一对号入座：

提供商 ID（JSON 中的 id）	base_url	env_key	wire_api
zai	https://api.z.ai/api/paas/v4	ZAI_API_KEY	chat
zai-coding-plan	https://api.z.ai/api/coding/paas/v4	ZAI_API_KEY	chat
zhipuai	https://open.bigmodel.cn/api/paas/v4	ZHIPU_API_KEY	chat
zhipuai-coding-plan	https://open.bigmodel.cn/api/coding/paas/v4	ZHIPU_API_KEY	chat

从源码结构可以推断：四个内置提供商统一走 wire_api = "chat"（OpenAI 兼容 Chat 格式），差别仅在于 base_url 指向通用端点还是 Coding Plan 端点。zai 的模型优先级排序（sort_priority: 36）与 zhipuai（sort_priority: 35）在 provider_catalog_overrides.json 中有明确定义，用于 /model 选择器的展示排序；同时该文件还通过 live_model_sources.zai（URL 为 https://api.z.ai/api/paas/v4/models，auth_env 同时接受 ZAI_API_KEY 与 ZHIPU_API_KEY）声明了运行时拉取在线模型列表的来源。这意味着你看到的模型 ID 并非写死的静态表，而是"静态目录 + 在线同步"相结合的结果。

从内置提供商开始：两条最简启动路径

交互式选择

先导出账户密钥，再启动 interpreter，用斜杠命令 /model 交互式选择提供商与模型：

export ZAI_API_KEY="..."
interpreter

命令行一步直达 Coding Plan

如果明确知道自己要用 Z.AI 的 GLM Coding Plan，可以在启动参数中直接锁定提供商和模型，跳过交互选择：

ZAI_API_KEY="..." interpreter \
  -c 'model_provider="zai-coding-plan"' \
  -m glm-5.2

其中 -c 传入 TOML 形式的配置片段，-m 指定模型 ID。若使用通用 Z.AI API，把 model_provider 改为 zai 即可；使用中国区服务的用户应改用 zhipuai 或 zhipuai-coding-plan，并配套导出 ZHIPU_API_KEY：

export ZHIPU_API_KEY="..."
interpreter   # 之后在 /model 中选择 zhipuai / zhipuai-coding-plan

这些捆绑提供商的默认行为是：请求经 OpenAI 兼容 Chat 端点发送，未显式指定 harness 时，使用 Open Interpreter 的通用 Chat 代理界面（默认代理形态，而非 ZCode 形态）。关于更完整的配置字段说明，可参考 docs/zh/config-reference.md 与 docs/zh/providers.md。

使用 ZCode Harness：复现原生编码代理形态

什么是 zcode

zcode 是 Open Interpreter 在原生 Rust 运行时中对 ZCode 形态的完整复刻，涵盖：ZCode 风格的系统提示（system prompt）、Messages 请求格式、工具集、待办事项（todos）、计划控制（plan controls）、技能（skills）、会话上下文（session context）以及子代理（subagent）行为。

代码实现集中在 codex-rs/core/src/harness/zcode.rs（约 2685 行），从源码可见其工作方式：

• 通过 include_str!("zcode_tools.json") 内嵌工具定义（见 zcode_tools.json），构建 Anthropic Messages 格式的工具声明；
• 系统提示直接以 "You are ZCode, an interactive coding agent" 开头，并注入计划模式（Plan mode）、TodoWrite 陈旧提醒等 system-reminder 控制块；
• 声明了 ZCODE_VERSION、ZCODE_USER_AGENT（如 ZCode/0.14.8 ...）等常量，模拟 ZCode 客户端的请求特征；
• 内置针对会话压缩（compaction）与"读取会话上下文"子任务（ReadSessionContext）的专用提示词，说明其会话上下文与子代理行为均有独立的提取/压缩模型路径。

需要强调的是它的硬性前提：zcode 需要一个 Anthropic Messages 兼容的提供商（即 wire_api = "messages"）。如果在内置 Chat 提供商（wire_api = "chat"）上仅把 harness 设为 zcode，并不会激活 Messages 请求路径，表现仍会是通用 Chat。

在 config.toml 中注册 Messages 提供商

Z.AI 官方为 Coding Plan 提供了 Anthropic 兼容端点（base URL 为 https://api.z.ai/api/anthropic）。把它注册到 ~/.openinterpreter/config.toml：

model_provider = "zai-zcode"
model = "glm-5.2"
harness = "zcode"

[model_providers.zai-zcode]
name = "Z.AI ZCode"
base_url = "https://api.z.ai/api/anthropic"
env_key = "ZAI_API_KEY"
wire_api = "messages"
env_http_headers = { Authorization = "ZAI_AUTHORIZATION" }

字段含义：

• 顶层 model_provider / model / harness 决定本次会话的默认提供商、模型与代理形态；
• [model_providers.zai-zcode] 声明一个自定义提供商 zai-zcode：base_url 指向 Anthropic 兼容端点，env_key = "ZAI_API_KEY" 声明该提供商所需的密钥来自环境变量 ZAI_API_KEY，wire_api = "messages" 声明线上格式为 Anthropic Messages；
• env_http_headers = { Authorization = "ZAI_AUTHORIZATION" } 表示在 HTTP 请求头写入 Authorization，其值从环境变量 ZAI_AUTHORIZATION 读取。

这样密钥不会以明文形式落盘到配置文件，而是留在环境中：

export ZAI_API_KEY="..."
export ZAI_AUTHORIZATION="Bearer $ZAI_API_KEY"
interpreter

Open Interpreter 会把 ZCode 的 Messages 请求发送到该 base URL 下的 /v1/messages。额外的 ZAI_AUTHORIZATION 环境变量对应 Z.AI 文档所描述的 bearer-token 认证方式，而 ZAI_API_KEY 仍是该提供商在解析阶段必需的密钥来源（对应 env_key 声明）。也就是说：配置里声明密钥来源，运行时用另一个变量注入认证头，两者各司其职。

wire_api 与 harness 的路由一致性

wire_api 与 harness 必须匹配，这一点在源码中有测试佐证。在 codex-rs/core/src/harness/routing.rs 中，Harness 枚举将 ZCode 序列化为字符串 "zcode"，且存在路由测试 zcode_messages_wire_uses_messages_harness_route：

fn zcode_messages_wire_uses_messages_harness_route() {
    assert_eq!(
        resolve_stream_transport_route(WireApi::Messages, &Harness::ZCode)
            .expect("messages zcode route"),
        StreamTransportRoute::MessagesHarness(MessagesHarnessRoute::ZCode)
    );
}

可以推断：只有当 WireApi::Messages 与 Harness::ZCode 同时成立时，请求才会被路由到专门的 MessagesHarnessRoute::ZCode 处理管线；若 wire_api 是 Chat，则不会命中该路由。这正是文档反复强调"端点、wire API 与 harness 三者必须一致"的实现根基。

选择 GLM 模型：信任 /model 而不是手抄 ID

官方建议优先使用交互式 /model 选择器，而不是在脚本或配置里维护一份私有的模型 ID 列表。原因在于：该选择器由维护中的提供商来源生成（见上文 live_model_sources），始终反映所选服务当前可用的 GLM 模型 ID。

以仓库当前目录为例，zai-coding-plan 的模型目录（provider_catalog.json）中就包含 glm-4.7、glm-5.1、glm-5.2、glm-5v-turbo 等多个条目，其中 glm-5.2 标注了 1000000 token 的 context window 与 reasoning: true；zhipuai-coding-plan 则提供 glm-5.1、glm-5v-turbo、glm-5-turbo、glm-4.5-air 等。注意不同提供商/地区的模型集并不相同——这正是文档警告"不要从其他 Z.AI 区域或计划复制模型 ID"的原因。

同时要理解：Z.AI 可能在服务端独立于 Open Interpreter 更新模型映射、计划资格与配额倍率。若出现模型不可用、或调用成本与预期不符（配额倍率变化）等情况，应以 Z.AI 官方当前的模型切换指引为准，并回到 /model 重新确认该提供商提供的模型。

Chat 还是 ZCode：按目标选择配置

目标	推荐配置
使用内置选择器的最简配置	zai-coding-plan 或 zai，通用 Chat
提供商推荐的 OpenAI 兼容集成	内置提供商，wire_api = "chat"
ZCode 形态的编码代理行为	自定义 Messages 提供商 + harness = "zcode"

配置禁忌（三类对象必须对齐）：

• 不要在 OpenAI 兼容的 /paas/v4 端点上设置 wire_api = "messages"——该端点不提供 Messages 格式；
• 不要把 Chat 提供商（base_url 为 /paas/v4）指向 /api/anthropic——端点与 wire API 不匹配；
• harness = "zcode" 必须配合 wire_api = "messages" 提供商，否则不会走 ZCode 管线。

判断标准很简单：看你的 base_url 落在哪类端点（Chat 还是 Anthropic），再决定 wire_api 与 harness，三者保持一致即可。端到端的沙箱与权限控制等通用能力仍然由 Open Interpreter 的 exec 层负责，与所选提供商无关（可参考 docs/zh/exec.md 与 docs/zh/execpolicy.md）。

编辑器和 SDK：让配置接入更广的工作流

两种配置（Chat 提供商 与 ZCode + Messages 提供商）都可以接入下游工具：

• ACP 兼容编辑器：通过 interpreter acp 启动 ACP（Agent Client Protocol）服务，即可在支持 ACP 的编辑器中复用当前会话，详见 docs/zh/acp.md；
• Codex SDK 兼容层：Open Interpreter 对外提供 Codex SDK 兼容接口，可将其作为 OpenAI Codex 的本地替代接入既有应用，详见 docs/zh/sdk.md。

无论走哪条通道，所选的提供商与 harness 都是 Open Interpreter 配置的一部分——SDK/ACP 只是外层传输与协议适配，不改变模型提供商与代理形态的设置逻辑。

故障排除

官方文档给出了四条高度凝练的排查经验，结合上文源码可做如下展开：

• 401 / 403 鉴权失败：通常是四类原因——密钥错误（env_key 对应的环境变量未导出或写错）、端点错误（Coding Plan 请求发到了通用端点或反之）、地区错误（全球 Z.AI 与中国智谱的密钥/端点不通用）、授权头错误（env_http_headers 中声明的环境变量未按 Bearer ... 格式注入）。
• Coding Plan 配额未生效：确认提供商确实是 zai-coding-plan / zhipuai-coding-plan（而不是 zai / zhipuai）；对于 ZCode 配置，则确认其 base_url 指向 /api/anthropic（该端点对应 Coding Plan 订阅）。
• /harness 显示 zcode 但行为仍像通用代理：几乎可以断定当前提供商没有真正走 Messages 路径——请检查该提供商的 wire_api = "messages" 是否生效（对应上文 routing.rs 中的路由断言逻辑）。
• 找不到某个模型：打开 /model，从该特定提供商的目录中选择，而不是从其他 Z.AI 区域或计划复制模型 ID——不同服务商的目录本就不同（如 zai-coding-plan 与 zhipuai-coding-plan 的模型集合存在差异）。

小结

把 Z.AI / Zhipu AI 的 GLM 模型接入 Open Interpreter 的关键，是理解"账户 → 提供商 → wire_api → harness"这条完整链路：账户决定凭证与地区（ZAI_API_KEY vs ZHIPU_API_KEY），提供商 ID 决定端点（通用 vs Coding Plan），wire_api 决定请求格式（Chat vs Messages），harness 决定代理形态（通用 Chat vs ZCode）。内置目录定义在 provider_catalog.json，ZCode 的实现可深读 zcode.rs，路由一致性可对照 routing.rs。把端点、wire API 与 harness 三者对齐，无论走通用 Chat 还是原生 ZCode 编码工作流，都能获得稳定一致的 GLM 编码体验。