Open Interpreter 接入 Z.AI 与 GLM 全攻略：从通用 Chat 到原生 ZCode 编码 Harness

本指南以 docs/zai-glm.md 为骨架，系统讲解如何在 Open Interpreter 中接入全球版 Z.AI、中国版 Zhipu AI 及其各自 GLM Coding Plan 订阅，覆盖四个内置 Provider 的选型、启动方式、模型选择，并深入剖析「通用 Chat 代理」与「原生 zcode 编码 harness」两条技术路线之间的本质区别。读完本文，你将能独立完成从导出 API Key、配置 ~/.openinterpreter/config.toml、选定 GLM 模型，到在 ACP 编辑器与 Codex SDK 中复用整套配置的完整落地。

Open Interpreter 是一个面向开源与开放模型的编码代理运行时，其 Rust 核心位于 codex-rs/，而本文聚焦的 Z.AI / GLM 能力同时体现在「内置 Provider 目录」与「zcode harness 实现」两层。我们会把文档中的每一步操作，与仓库内的真实配置与源码一一对应起来。

选择合适的 Provider

Open Interpreter 为 GLM 生态提供了两组、共四个内置 Provider。选择哪一个，取决于你的账户体系（全球版 Z.AI 还是中国版 Zhipu AI）以及你是否拥有 Coding Plan 订阅：

账户或服务	Provider 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

这四个 Provider 的真实定义可以在内置目录 codex-rs/model-provider-info/provider_catalog.json 中直接核对：

• zai：base_url = https://api.z.ai/api/paas/v4，env_key = ZAI_API_KEY，wire_api = chat；
• zai-coding-plan：base_url = https://api.z.ai/api/coding/paas/v4，env_key = ZAI_API_KEY，wire_api = chat；
• zhipuai：base_url = https://open.bigmodel.cn/api/paas/v4，env_key = ZHIPU_API_KEY，wire_api = chat；
• zhipuai-coding-plan：base_url = https://open.bigmodel.cn/api/coding/paas/v4，env_key = ZHIPU_API_KEY，wire_api = chat。

Z.AI 官方将通用端点与 Coding Plan 端点在文档上明确分离：只有具备订阅资格时，才应选用 *-coding-plan 提供商；使用通用端点不会消耗 Coding Plan 配额。因此在依赖订阅配额之前，请先确认自己的客户端与使用场景符合 Z.AI 当前生效的 Coding Plan 使用政策。仓库中的 Provider 目录仅负责描述端点和模型元数据（模型目录测试 亦在持续断言 zhipuai、zai、zhipuai-coding-plan 等 ID 始终存在），订阅资格本身由服务端裁决，这也是文档反复强调配额归属的原因。

从内置 Provider 开始：三分钟跑通 GLM

最快的上手路径不需要任何手写配置。先导出账户密钥，启动 Open Interpreter，再在交互界面里用 /model 选择对应的 Provider 与模型：

export ZAI_API_KEY="..."
interpreter

若你持有 Z.AI 的 GLM Coding Plan 订阅，也可以直接通过命令行参数一次性指定 Provider 与模型完成启动：

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

这里 -c 接受一段内联 TOML 配置（等效于修改 ~/.openinterpreter/config.toml 中的 model_provider），-m 则直接指定模型 ID。若使用通用 Z.AI API，将 Provider 换成 zai 即可；使用中国区服务的用户则应选用 zhipuai 或 zhipuai-coding-plan 并配合 ZHIPU_API_KEY。

这一层的实现事实是：内置 Provider 一律走 OpenAI 兼容的 Chat 端点（wire_api = "chat"），在 codex-rs/core/src/harness/routing.rs 的路由逻辑中，(WireApi::Chat, _) 的兜底分支会落到 ChatCompletionsCompat 传输路径。若未显式指定 harness，它们使用的就是 Open Interpreter 的通用 Chat 代理界面——也就是说，「内置 Provider + 通用 Chat」是最简单、最少自定义的配置组合。

升级到编码代理形态：配置 ZCode Harness

通用 Chat 之外，仓库还内置了一个更高阶的选项：zcode。它是 Open Interpreter 在原生 Rust 运行时里对「ZCode 形态」完整复刻的 harness——包括其形态的系统提示、Messages 请求格式、工具集、待办事项、计划控制、技能、会话上下文以及子代理（subagent）行为。

需要特别强调的是 harness 与 wire API 的耦合关系：zcode 依赖 Anthropic Messages 兼容的传输层。如果你只是在内置 Chat Provider 上把 harness 选成 zcode，Messages 路由并不会被激活，行为依然停留在通用 Chat。

Z.AI 官方为 Coding Plan 提供了 Anthropic 兼容端点 https://api.z.ai/api/anthropic。要使用它，需要在 ~/.openinterpreter/config.toml 中新增一个 Messages 形态的自定义 Provider：

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" }

随后在不把密钥明文写进配置文件的前提下，通过环境变量暴露 bearer 请求头：

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

Open Interpreter 会把 ZCode 形态的 Messages 请求发送到 /v1/messages。这里的关键设计是双环境变量分工：ZAI_AUTHORIZATION 这个额外授权变量对应 Z.AI 文档要求的 bearer-token 认证，而 env_key 指向的 ZAI_API_KEY 仍然是 Provider 所必需的密钥来源。

逐字段理解自定义 Provider 配置

上述 TOML 的语义可以在 docs/providers.md 中找到完整解释，核心字段作用如下：

• model_provider / model / harness 三个顶层键共同决定「用哪家端点、跑哪个模型、以何种代理形态工作」，也可在会话内用 /model、/harness 命令动态调整；
• name：Provider 在 UI 中的展示名；
• base_url：请求发往的端点根地址；
• env_key：从环境变量读取 bearer token（providers.md 将其列为鉴权方式之一）；
• wire_api：控制 HTTP 请求的形态，可选值与语义为 chat（OpenAI 兼容 Chat Completions）、messages（Anthropic Messages）、responses（OpenAI Responses 兼容）；其中 messages 只应配给 Anthropic Messages 兼容端点；
• env_http_headers：附加 HTTP 请求头，此处用它把 ZAI_AUTHORIZATION 注入为 Authorization 头，密钥本身依然留在环境变量里。

从源码看 ZCode Harness 的实现细节

如果希望深入理解 zcode 到底复刻了什么，可以直接阅读 codex-rs/core/src/harness/zcode.rs。这个约 2685 行的文件是 ZCode 形态的完整实现，可从中观察到的实现事实包括：

• 系统提示以 "You are ZCode, an interactive coding agent"（ZCODE_SYSTEM_HEADER）为头部，并内置了完整的 ZCode harness 行为说明、计划模式（Plan mode）工作流提醒、TodoWrite 状态提醒、以及会话压缩（compaction）专用的 ZCODE_COMPACTION_PROMPT；
• 请求通过 build_request 组装成 AnthropicMessageRequest（即 Anthropic Messages 格式），这与配置中 wire_api = "messages" 的要求完全对应；
• 工具清单从同目录的 zcode_tools.json 以 include_str! 方式编译期内嵌（zcode.rs），并带有版本号常量 ZCODE_VERSION（如 0.14.8）；
• 另有 zcode_skill_creator.md 等伴随资源，支撑文档中提到的「技能」能力。

路由侧的证据同样直接：在 codex-rs/core/src/harness/routing.rs 中，(WireApi::Messages, Harness::ZCode) 被显式映射为 MessagesHarnessRoute::ZCode，从而进入 Messages 传输路径。反过来，如果 harness 是 zcode 但 wire 是 Chat，兜底分支只会把它当作 ChatCompletionsCompat 处理——这正是文档 Troubleshooting 一节「/harness 显示 zcode 但行为却像通用 Chat」的源码层原因。

选择 GLM 模型：用 /model 而不是私人清单

不建议手工维护模型 ID 清单，理由是模型目录由仓库持续维护，/model 选择器会直接从这些来源生成，天然包含所选服务当前可用的模型 ID。这一点有明确的仓库证据：内置目录 provider_catalog.json 中 zai-coding-plan 条目下当前列出 glm-5.2（100 万 context window）、glm-5.1、glm-5-turbo、glm-5v-turbo、glm-4.7 与低价档位的 glm-4.5-air；zhipuai-coding-plan 则额外包含 glm-4.6v、glm-4.5-air 等。而 zai 通用端点当前的模型序列以 glm-4.7、glm-4.5、glm-4.5v、glm-4.5-flash 等按量付费型号为主——同一模型在不同 Provider（通用 vs Coding Plan）下的可用性并不一致。

因此正确的做法是：打开 /model，在当前选中的 Provider 范围内挑选模型。Z.AI 可能独立于 Open Interpreter 在服务端更新模型映射与订阅资格，当某个模型不可用、或计费倍率发生变化时，应以该服务当前的模型切换说明为准，而不是把一个区域/计划的模型 ID 直接抄到另一套配置里。

Chat 还是 ZCode：如何决策

两种形态面向不同目标，文档给出了一张清晰的决策对照表：

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

选择的核心约束是「端点、wire API、harness 三者必须自洽」。两条典型反例是：不要在 OpenAI 兼容的 /paas/v4 端点上设置 wire_api = "messages"，也不要把 Chat Provider 指向 /api/anthropic。从 routing.rs 的分发逻辑可以验证：当 wire_api 与 harness 不匹配时，部分组合会被直接判为非法请求（例如 wire_api = "messages" 与若干 Chat 系 harness 组合返回 InvalidRequest），而另一些组合则会被静默降级为通用 Chat——前者报错、后者「看起来没生效」，两种坑都源于同一根因。

在编辑器与 SDK 中复用同一套配置

上述两种配置（通用 Chat 与 ZCode）并不局限于终端。二者都可以通过 interpreter acp 暴露给 ACP 兼容的编辑器（参见 docs/acp.md），也可以通过 Open Interpreter 的 Codex SDK 兼容层以编程方式驱动（参见 docs/sdk.md）。无论从哪个入口接入，所选 Provider 与 harness 都始终是 Open Interpreter 配置的一部分——也就是说，一次配置，多处复用，/model 与 /harness 的选型结果会自动随会话迁移。

故障排除清单

把文档中的经验与上文源码分析合并，可以得到一套可执行的排障路径：

• 出现 401 或 403：通常意味着密钥、端点、地区或授权头其中一项用错了。先核对 env_key 指向的环境变量是否已导出、值是否为「密钥本体」（而非拼好的 Bearer ... 字符串）；再确认配置的是 api.z.ai 还是 open.bigmodel.cn、走的是通用还是 /coding/ 前缀端点。
• Coding Plan 配额一直没被消耗：确认当前 Provider 确为 zai-coding-plan（或 zhipuai-coding-plan）；若走 ZCode 路线，则确认 base_url 指向 /api/anthropic 而非通用 Chat 端点。
• /harness 已显示 zcode，但行为仍像通用 Chat：检查当前 Provider 的 wire_api 是否为 messages。只有 wire_api = "messages" 与 harness = "zcode" 的组合才会进入 MessagesHarnessRoute，这是 routing.rs 中可验证的硬性约束。
• 模型在下拉列表里找不到：打开 /model，在该 Provider 专属的模型序列内选择，而不要从其他 Z.AI 区域或计划复制模型 ID——因为不同 Provider 的模型目录在 provider_catalog.json 中本就各不相同。

小结

从「内置 Provider + 通用 Chat」到「自定义 Messages Provider + zcode harness」，Open Interpreter 为 GLM 模型提供了从轻量问答到完整编码代理的渐进式接入路径。二者的分水岭在于 wire API 与 harness 的匹配：前者基于 OpenAI 兼容的 /paas/v4 Chat 端点开箱即用，后者则需要在 ~/.openinterpreter/config.toml 中定义指向 /api/anthropic 的 Messages Provider，并显式声明 harness = "zcode"。相关参考文档还包括 docs/providers.md（Provider 与 harness 总览）与 docs/harness.md（harness 兼容矩阵），以及本文的 中文原始版本。