OpenClaw Z.AI 插件深入解析openclaw/zai-provider的分发、端点自动探测与 GLM 模型运行时机制【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库中的 Z.AI 插件参考文档为骨架结合插件源码extensions/zai/与插件清单系统讲清openclaw/zai-provider的分发方式、四个 Z.AI 端点的自动探测流程、GLM 模型目录、思考级别thinking level到reasoning_effort的映射、工具流与“保留思考”等运行时补丁机制以及图片理解与用量查询两个注册契约。读完后可独立完成 Z.AI/GLM 模型在 OpenClaw 中的安装、接入与排查。1. 插件定位与分发渠道Z.AI 是 GLM 模型系列的 API 平台。在 OpenClaw 中它通过一个名为zai的 provider 接入承载该 provider 的正是本插件。官方参考文档 Z.AI plugin reference 对其定位的概括是Adds Z.AI model provider support to OpenClaw.该文档头部明确标注它是自动生成文件Generated file. Do not edit by hand通过运行pnpm plugins:inventory:gen重建只有位于openclaw-plugin-reference:manual-start与openclaw-plugin-reference:manual-end注释标记之间的手写文本才会被保留。因此把它当作插件的“机器可读摘要”配合人工撰写的 Z.AI 提供商文档 一起阅读最为合适。参考文档给出的两个核心事实分发渠道包名openclaw/zai-provider安装路由npm 或 ClawHub即clawhub:openclaw/zai-provider。Surface对外暴露面ProviderszaiContractsmediaUnderstandingProviders、usageProviders。这两点在插件元数据里可以得到逐一印证。package.json 声明了包名openclaw/zai-provider并在openclaw.install段中同时给出npmSpec: openclaw/zai-provider与clawhubSpec: clawhub:openclaw/zai-provider默认渠道为 npm还要求宿主版本2026.6.9、插件 API2026.9.3。插件安装方式见 插件 READMEopenclaw plugins install openclaw/zai-provider2. 清单manifest里的完整 Surface 定义插件行为大量声明在 openclaw.plugin.json 中这是理解该插件能力边界的最佳入口Provider 声明providers: [zai]并声明端点类别endpointClass: zai-native宿主为api.z.ai请求按family: zai归类providerRequest段。认证方式声明setup.providers[0]指定authMethods: [api-key]接受的环境变量为ZAI_API_KEY与旧别名Z_AI_API_KEY。模型目录modelCatalog内置了完整的 GLM 模型行见第 4 节并声明了别名z.ai、z-ai到 providerzai的映射以及discovery: { zai: refreshable }模型可刷新发现。注册契约contractscontracts: { mediaUnderstandingProviders: [zai], usageProviders: [zai] }这与参考文档 “Surface → Contracts” 一节完全对应插件一方面注册图片理解 provider另一方面注册用量usageprovider。图片理解元数据mediaUnderstandingProviderMetadata.zai声明能力为image默认模型glm-4.6v自动选择优先级autoPriority.image 60。认证选项providerAuthChoices声明了 5 个 onboarding 选项zai-api-key、zai-coding-global、zai-coding-cn、zai-global、zai-cn统一使用 CLI 选项--zai-api-key key传入密钥。3. 四个端点与自动探测机制Z.AI 对同一 API key 区分两种 API 面general API 与 Coding Plan和两个地域Global / CN组合出四个 base URL。Z.AI 提供商文档 给出的端点表如下Onboarding 选项Base URL默认模型zai-globalhttps://api.z.ai/api/paas/v4glm-5.2zai-cnhttps://open.bigmodel.cn/api/paas/v4glm-5.2zai-coding-globalhttps://api.z.ai/api/coding/paas/v4glm-5.3zai-coding-cnhttps://open.bigmodel.cn/api/coding/paas/v4glm-5.3这些 URL 在源码 model-definitions.ts 中是四个导出常量ZAI_GLOBAL_BASE_URL、ZAI_CN_BASE_URL、ZAI_CODING_GLOBAL_BASE_URL、ZAI_CODING_CN_BASE_URL并通过resolveZaiBaseUrl(endpoint)做端点到 URL 的映射缺省回落到 global 端点。3.1zai-api-key的自动探测流程使用zai-api-key选项时OpenClaw 会用你的 key 逐个探测端点并自动落配置。核心实现在 detect.ts 的detectZaiEndpoint探测顺序先 general 端点global→cn以glm-5.2为探测模型再 Coding Plan 端点coding-global→coding-cn以glm-5.3为探测模型命中第一个接受请求的端点即停止。这与提供商文档描述一致。探测动作向baseUrl/chat/completions发起最小化非流式请求max_tokens: 1消息内容pingBearer 认证HTTP 2xx 即判定通过见 probeZaiChatCompletions。失败分类404、错误码1211/1311、或 400 且错误文本匹配 “model not found / 模型不存在” 等模式被归类为“该端点不支持此模型”而非 key 无效——这决定了是否会继续尝试下一个候选isUnsupportedModelResult。降级候选Coding Plan 端点若不支持 GLM-5.3会依次回退探测glm-5.1再回退glm-4.7fallback 候选并在成功时附带一条说明性note。这正是提供商文档中“auto-detection falls back throughglm-5.1andglm-4.7”的来源。安全边界探测对错误响应体设置了 16 MiB 读取上限ZAI_DETECT_ERROR_BODY_MAX_BYTES并整体受超时控制避免把不可信的错误响应无界缓冲进内存。探测成功后返回{ endpoint, baseUrl, modelId, note }由 index.ts 中的runZaiApiKeyAuth写入认证 profilezai:default并调用applyZaiProviderConnectionConfig生成配置补丁baseUrl 模型目录预设 默认模型引用。若 key 在四个端点都探测失败交互式流程会弹出端点选择器promptForZaiEndpoint由用户手动指定global/cn/coding-global/coding-cn。3.2 端点选择写入配置的逻辑onboard.ts 负责把“端点 模型”翻译为配置resolveZaiModelId的规则显式指定modelId时优先使用否则端点以coding-开头或 baseUrl 命中两个 coding URL 之一时默认glm-5.3ZAI_CODING_DEFAULT_MODEL_ID否则默认清单中的glm-5.2。applyZaiPreset调用插件 SDK 的applyProviderConfigWithModelCatalogPreset写入api: openai-completions、baseUrl、模型目录并额外注册别名GLM指向默认模型引用同时把zai/modelId设为 primary 模型。这也解释了提供商文档中的一句话“Fresh Coding Plan setup defaults tozai/glm-5.3; general API setup remains onzai/glm-5.2.”4. 内置模型目录manifest-backed catalog参考文档提到插件把目录打包在 manifest 里因此只读的models list不需要加载 provider 运行时即可展示模型行。openclaw.plugin.json 中的目录内容如下模型 ID名称上下文窗口最大输出输入模态输入/输出价格每百万 token备注glm-5.3GLM-5.31,048,576131,072text0 / 0Coding Plan 默认本地目录计价为 0按套餐配额计费glm-5.3-flashGLM-5.3-Flash1,048,576131,072text image0.15 / 0.5缓存读 0.03多模态文本与图像glm-5.2GLM-5.21,000,000131,072text1.4 / 4.4缓存读 0.26General API 默认glm-5-turboGLM-5-Turbo200,000131,072text1.2 / 4缓存读 0.24文本模型glm-5v-turboGLM-5V-Turbo200,000131,072text image1.2 / 4缓存读 0.24多模态编码模型glm-5.1GLM-5.1200,000131,072text1.4 / 4.4缓存读 0.26status: deprecated由glm-5.2替代其中glm-5.3、glm-5.3-flash、glm-5.2、glm-5.1带有compat: { codeMode: preferred }标记。目录构建逻辑在 buildZaiCatalogModels直接从 manifest 解析出的 provider 配置复制模型行避免运行时硬编码。查看当前安装版本已知目录的命令openclaw models list --all --provider zai关于计价的细节提供商文档说明GLM-5.3 目前是 Coding Plan 模型本地目录成本记为 0因为订阅走套餐配额而非按 token 计费glm-5.3-flash即使有临时折扣也按目录中的按量价格计算。5. 认证方式与配置示例5.1 认证要点源自插件文档与 manifestZ.AI 使用 Bearer 认证环境变量为ZAI_API_KEY旧别名Z_AI_API_KEY仍被接受——启动时若ZAI_API_KEY未设置OpenClaw 会把Z_AI_API_KEY复制过去插件入口 index.ts 中envVars: [ZAI_API_KEY, Z_AI_API_KEY]与此对应。zai-api-key选项自动探测匹配端点并应用正确的 base URLzai-coding-global/zai-coding-cn/zai-global/zai-cn强制指定某一 API 面。若 key 同时能工作于两种面用显式选项可强制落到 Coding Plan 端点。5.2 接入步骤# 1. 安装 provider 插件 openclaw plugins install openclaw/zai-provider # 2. 运行 onboarding自动探测端点 openclaw onboard --auth-choice zai-api-key # 或强制指定端点 openclaw onboard --auth-choice zai-coding-global # 3. 验证模型已列出 openclaw models list --all --provider zai5.3 手动配置示例提供商文档给出的完整配置可直接复制到 OpenClaw 配置中{ env: { vars: { ZAI_API_KEY: sk-... } }, models: { providers: { zai: { // GLM-5.3 使用 Coding Plan 端点 baseUrl: https://api.z.ai/api/coding/paas/v4, }, }, }, agents: { defaults: { model: { primary: zai/glm-5.3 } } }, }排查端点配置可用openclaw models list --all --provider zai openclaw config get models.providers.zai.baseUrl6. 思考级别Thinking Levels的映射实现不同 GLM 模型对 reasoning 参数的支持不同插件为此实现了逐模型的策略层 provider-policy-api.tsGLM-5.3 / Flash级别low、high、max默认max。源码映射表ZAI_REASONING_EFFORT_MAPS[5.3]把off/minimal/low映射到 Z.AI 的reasoning_effort: low因为 GLM-5.3 不支持彻底关闭推理medium/high映射到highxhigh/adaptive/max映射到max。GLM-5.2全范围off、low、high、max默认off映射low/high→high、max→max。其他 GLM 模型只有二元开关off与low选择器中显示为on默认off。设置为off时发送thinking: { type: disabled }其他级别不改动请求体。resolveThinkingProfile第 45-77 行向选择器暴露上述级别与默认值。文档同时解释了一个实用点把 thinking 设为off可以避免回复把输出预算消耗在可见文本之前的reasoning_content上。请求体补丁由 wrapZaiStreamFn 统一处理仅对openai-completionszai组合生效disableThinking时注入thinking: { type: disabled }解析出reasoningEffort时注入reasoning_effort开启保留思考时注入thinking: { type: enabled, clear_thinking: false }。7. 高级配置工具流、保留思考与未知模型前向兼容提供商文档列出的四个高级配置项均可在源码中找到对应实现工具流tool_stream默认开启。关闭方式为每模型参数{ agents: { defaults: { models: { zai/model: { params: { tool_stream: false } }, }, }, }, }对应源码wrapZaiStreamFn第一行即createToolStreamWrapper(ctx.streamFn, ctx.extraParams?.tool_stream ! false)——只有显式false才关闭prepareExtraParams则通过defaultToolStreamExtraParams向额外参数中预置默认值。保留思考preserveThinking因 Z.AI 要求完整回放历史reasoning_content会增加 prompt token 数默认关闭需按模型显式开启{ agents: { defaults: { models: { zai/glm-5.3: { params: { preserveThinking: true } }, }, }, }, }启用且 thinking 开启时请求会带thinking: { type: enabled, clear_thinking: false }并回放同一 OpenAI 兼容转录中的历史reasoning_contentsnake_case 键preserve_thinking作为别名同样生效见 shouldPreserveZaiThinking。高级用户仍可用params.extra_body.thinking直接覆盖 provider 请求体。未知 GLM-5 模型的前向解析清单目录外的glm-5*模型 ID 在 provider 路径上仍会被解析。resolveGlm5ForwardCompatModel 通过resolveFamilyForwardCompatModel以glm-4.7为模板合成 provider 自有元数据名称、baseUrl、api: openai-completions、上下文窗口等其中baseUrl优先取已配置的providerConfig.baseUrl确保原生模型“绝不下落到 OpenAI SDK 的默认主机”。图片理解插件注册了图片理解 providermedia-understanding-provider.ts默认模型glm-4.6v。它自动从已配置的 Z.AI 认证解析无需额外配置autoPriority.image 60决定其在多 provider 竞争时的自动选择优先级。8. 用量查询契约usageProviders参考文档 Surface 中的第二个契约usageProviders在入口 index.ts 中落实resolveUsageAuth按zai/z-ai两个 provider ID 从配置与凭据存储解析 API keyenvDirect覆盖ZAI_API_KEY与Z_AI_API_KEY两个环境变量找不到时回退读取历史~/.pi/agent/auth.json中z-ai/zai的访问令牌废弃路径的兼容保留fetchUsageSnapshot委托给插件 SDK 的fetchZaiUsage(token, timeoutMs, fetchFn)拉取用量快照isCacheTtlEligible: () true允许对结果做 TTL 缓存。9. 速率限制、过载与错误排查Z.AI 将 Coding Plan 与通用 agent 工具都作为容量管理服务。提供商文档整理的关键行为通用 agent 工具按尽力best-effort提供服务新加坡时间约 2–6 点高峰期可能出现临时限流Coding Plan 的速率与并发限制绑定套餐层级并随资源情况动态调整API 错误码1302表示“请求速率限制达到上限”1305表示“服务可能暂时过载请稍后重试”。实操建议高峰期出现临时429或1305时等待重试即可若峰谷期均可复现、或只发生在某一端点/模型/请求形态上优先检查端点与模型配置命令见第 5.3 节。Coding Plan key 应配 Coding Plan 端点如https://api.z.ai/api/coding/paas/v4通用 API key 应配通用端点如https://api.z.ai/api/paas/v4——同一 key 同一端点的持续性失败更可能是 provider 侧拒绝或套餐限制而非普通高峰限流。从源码结构看插件还自带上下文超限识别matchesContextOverflowError用正则匹配 “tokens in request more than max tokens allowed / prompt exceeds max length” 类错误信息index.ts 第 358-361 行配合buildProviderReplayFamilyHooks({ family: openai-compatible, dropReasoningFromHistory: false })参与 OpenClaw 的上下文溢出恢复与历史回放策略。10. 测试如何验证探测逻辑探测逻辑的回归测试在 detect.test.ts 中通过注入假fetchFn覆盖关键场景端点优先级与回退global 端点返回 404 时落到 cn再落到 coding-globalglm-5.3探测成功等顺序断言错误体边界用 64 MiB 的流式错误响应验证 16 MiB 读取上限是“fail-closed”的消费者会取消流而不是把不可信响应全部读入内存非 JSON / 空 / 畸形错误体验证有界解码路径与旧res.json()路径行为一致。另外detectZaiEndpoint在 vitest 环境下process.env.VITEST且未注入fetchFn直接返回null避免测试环境产生真实网络探测。11. 小结与延伸阅读参考文档docs/plugins/reference/zai.md是自动生成摘要包名、安装路由、provider 与两个契约完整接入指引在 docs/providers/zai.md端点表、onboarding 选项、配置示例、模型目录、thinking 级别、高级配置实现细节集中在 extensions/zai/入口 index.ts认证方法、流补丁、动态模型解析、detect.ts端点探测、model-definitions.ts端点 URL 与目录构建、onboard.ts配置写入、provider-policy-api.tsthinking 策略、media-understanding-provider.ts图片理解以及 openclaw.plugin.json声明式清单。掌握上述内容后你既能按文档完成 Z.AI 的标准接入也能在端点选错、限流频发或 thinking 参数不生效时直接定位到对应源码模块进行排查。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考