企业官网建设流程全解析

Roo Code 接入 Z AI（GLM 系列模型）完整指南：区域路由、模型配置与思考模式解析

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

Z AI（智谱 AI）为 Roo Code 提供 GLM 系列大模型，并通过"区域感知路由"为国际用户与中国大陆用户分别提供独立接入端点与模型目录。本文将带你从申请 API Key 开始，完成在 Roo Code 中的 Z AI 提供商配置，并结合仓库源码剖析区域端点映射、模型定价参数、OpenAI 兼容格式以及 GLM-4.7/GLM-5 思考（thinking）模式的底层实现，让你既会配置、也懂原理。

Z AI 提供商概览：一条线路，两套端点

Z AI（Zhipu AI）提供 GLM 家族的多款语言模型，包括通用模型、轻量模型、免费高速模型与多模态视觉模型。其 API 服务在架构上区分国际版与国内版两个平台，因此 Roo Code 在接入时引入了"区域（Region）"这一核心概念：

• International（国际区）：面向全球用户，API 平台为z.ai，默认端点为https://api.z.ai/api/paas/v4；
• China（中国大陆区）：面向中国大陆用户，API 平台为 BigModel（open.bigmodel.cn），默认端点为https://open.bigmodel.cn/api/paas/v4。

区域设置同时决定两件事：目标 API 端点与可选模型目录。Roo Code 会根据所选区域自动拉取该区域可用的模型列表，无需手动维护。

第一步：获取 API Key

无论使用哪个区域，Z AI 都要求携带 API Key 发起请求，获取方式一致，仅平台入口不同。

国际用户

1. 访问z.ai的模型 API 页面（z.ai/model-api），注册或登录账号；
2. 进入账户控制台，找到API Keys区域；
3. 为你的应用生成一个新的 API Key；
4. 立即复制并妥善保存——API Key 只在创建时完整展示一次，关闭页面后将无法再次查看。

中国大陆用户

1. 访问 BigModel 开放平台（open.bigmodel.cn），注册或登录账号；
2. 进入账户控制台，找到API Keys区域；
3. 生成一个新的 API Key；
4. 立即复制并妥善保存。

注意：两个平台的 API Key 相互独立、不可混用，请根据你的区域选择在对应平台申请。

第二步：在 Roo Code 中配置 Z AI

1. 打开 Roo Code 设置：点击 Roo Code 面板右上角的齿轮图标（⚙）；
2. 选择提供商：在 "API Provider" 下拉框中选中Z AI；
3. 选择区域：根据你的访问位置选择区域：
   • International（默认）——全球访问；
   • China——中国大陆访问；
4. 填写 API Key：将上一步获取的 Key 粘贴到 "Z AI API Key" 输入框；
5. 选择模型：在 "Model" 下拉框中选择目标模型，可选模型由当前所选区域决定。

默认行为与关键特性

• Base URL 自动切换：选定区域后端点自动确定，无需手工填写：
  • International →https://api.z.ai/api/paas/v4
  • China →https://open.bigmodel.cn/api/paas/v4
• 动态模型列表：切换区域会自动刷新模型目录并同步更新目标端点；
• 通常无需自定义 Base URL：日常使用不需要额外配置自定义端点。

源码级剖析：区域与端点的真实映射

文档中"区域决定端点"的描述在源码中有精确对应。在 packages/types/src/providers/zai.ts 中定义了一份线路配置表zaiApiLineConfigs，它比 UI 上的两个区域更细，共包含四条线路：

其中international_coding与china_coding走.../coding/paas/v4编码专用端点，international_api与china_api走通用.../api/paas/v4端点。每条线路还带一个isChina布尔标记，用于决定加载哪一份模型目录。该线路字段在 packages/types/src/provider-settings.ts 中通过 Zod 枚举校验：zaiApiLineSchema = z.enum(["international_coding", "china_coding", "international_api", "china_api"])，配合zaiApiKey一起构成 Z AI 的配置 Schema。

在提供商实现端（src/api/providers/zai.ts），ZAiHandler继承自BaseOpenAiCompatibleProvider，其构造函数会根据options.zaiApiLine（缺省时默认"international_coding"）取出对应线路的isChina、baseUrl：

const isChina = zaiApiLineConfigs[options.zaiApiLine ?? "international_coding"].isChina const models = (isChina ? mainlandZAiModels : internationalZAiModels) as unknown as Record<string, ModelInfo> const defaultModelId = (isChina ? mainlandZAiDefaultModelId : internationalZAiDefaultModelId) as string super({ ...options, providerName: "Z.ai", baseURL: zaiApiLineConfigs[options.zaiApiLine ?? "international_coding"].baseUrl, apiKey: options.zaiApiKey ?? "not-provided", defaultProviderModelId: defaultModelId, providerModels: models, defaultTemperature: ZAI_DEFAULT_TEMPERATURE, })

由此可以推断：UI 上的"International / China"两个区域在底层会继续细分到 coding 与通用 API 线路，默认模型与模型目录则随isChina标记自动切换。

可用模型与定价参考（以仓库配置为准）

Roo Code 会自动从 Z AI API 拉取模型列表，但你无需依赖网络请求，仓库内的 packages/types/src/providers/zai.ts 已固化了两份模型目录，并附带了上下文窗口、最大输出、价格与缓存价格等元数据。

国际区模型目录（internationalZAiModels）：

中国区模型目录（mainlandZAiModels）与上述大体对应，但存在两个差异点：一是价格不同（例如glm-4.6输入 0.29、输出 1.14）；二是glm-4.6/glm-4.7的上下文窗口为 204,800，且不包含glm-4-32b-0414-128k。

两个区域的默认模型均为glm-4.6（见internationalZAiDefaultModelId与mainlandZAiDefaultModelId），在 packages/types/src/providers/index.ts 的getProviderDefaultModelId中，Z AI 的默认模型也会根据isChina标记分别返回。所有模型的默认采样温度统一为ZAI_DEFAULT_TEMPERATURE = 0.6。

上表价格取自仓库当前固化的元数据，实际计费以对应区域平台的最新定价为准。

思考（Thinking）模式：GLM-4.7/GLM-5 的特殊处理

这是 Z AI 接入中比较独特的实现细节。在模型目录中，glm-4.7与glm-5声明了supportsReasoningEffort: ["disable", "medium"]、reasoningEffort: "medium"与preserveReasoning: true，表示它们原生内置思考能力，且 API 默认开启 thinking。

这带来一个隐含问题：如果用户在 Roo Code 中关闭了推理（reasoning），而 API 侧 thinking 默认仍为开启，就会产生行为不一致。因此ZAiHandler重写了createStream方法（src/api/providers/zai.ts）：当检测到当前模型支持思考（Array.isArray(info.supportsReasoningEffort)）时，会调用自定义的createStreamWithThinking，通过shouldUseReasoningEffort判断用户当前是否开启推理，并显式向 API 发送 thinking 参数：

thinking: useReasoning ? { type: "enabled" } : { type: "disabled" },

即"用户开推理 → 显式enabled；用户关推理 → 显式disabled"，避免依赖 API 的默认开启行为。同时请求中仍携带max_tokens、temperature、stream: true、stream_options: { include_usage: true }、tools与parallel_tool_calls等标准 OpenAI 流式参数。

为交错思考优化的消息转换器

GLM-4.7/GLM-5 的思考模式还要求对话历史中的"推理内容"能被正确保留与回传。为此仓库提供了一个专用转换器 src/api/transform/zai-format.ts（convertToZAiFormat），其核心逻辑包括：

• 将 Roo Code 内部的 Anthropic 消息格式转换为 OpenAI Chat Completions 格式；
• 保留reasoning_content：将助手消息中的推理块提取并写回 OpenAI 消息的reasoning_content字段，实现交错思考（interleaved thinking）的连续对话；
• 合并工具结果后的文本：当mergeToolResultText: true时，工具结果（tool_result，如 environment_details）之后的文本会被合并进最后一条 tool 消息，而不是新开一条 user 消息——原因是 Z AI 一旦在历史中看到 user 消息就会丢弃此前所有的reasoning_content，破坏思考连续性。

从源码注释可以确认，这是为了让 Roo Code 的 Agent 循环（工具调用 → 环境反馈 → 继续思考）与 Z AI 的 thinking API 行为完全对齐而做的专门适配。

使用提示与注意事项

• 区域选择即端点选择：International→https://api.z.ai/api/paas/v4，China→https://open.bigmodel.cn/api/paas/v4，切换区域会自动更新模型目录，无需手工覆盖 Base URL；
• OpenAI 兼容协议：Z AI 提供 OpenAI 兼容 API，支持流式响应（streaming）与用量统计（usage reporting），这也是 Roo Code 通过BaseOpenAiCompatibleProvider快速接入的原因；
• 模型自动过滤：模型列表会依据所选区域自动过滤，确保候选模型与端点能力匹配，例如中国区不提供glm-4-32b-0414-128k；
• API Key 必需：所有请求都必须携带有效 Key，请确保从对应区域平台获取；未配置 Key 时ZAiHandler会回退为占位符"not-provided"，请求将失败；
• 思考模型注意推理开关：使用glm-4.7、glm-5时，建议根据任务复杂度在 Roo Code 中显式设置推理强度（medium / disable），Roo Code 会以thinking参数显式覆盖 API 默认行为；
• 价格查询：模型定价以各区域平台当前发布的价格为准，仓库中的inputPrice/outputPrice等字段仅为 Roo Code 成本估算所用。

完成以上配置后，即可在 Roo Code 中直接使用 GLM 系列模型驱动完整的 Agent 开发流程；如需了解其他提供商或进阶功能，可查阅仓库中的 providers 文档目录 与 Roo Code 使用指南。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code