在 macOS 上把 OpenClaw 网关接到智谱 GLM，2026 年推荐走官方 zai 供应商路径：用 openclaw onboard 选择 zai-api-key，在 ~/.openclaw/.env 写入 ZAI_API_KEY，默认模型引用 zai/glm-5.1。若团队购买的是 Coding Plan，还必须把流量打到 zai-coding-cn 端点，而不是通用对话 API——否则账单套餐与限流策略会对不上。本文按 OpenClaw GLM 供应商文档 与 智谱开放平台 整理 onboarding、openclaw.json 骨架、模型故障转移、429 重试 与 doctor 诊断，并说明为何大陆团队常在云 Mac mini 上做预发。
你将得到 Coding Plan 与通用 API 对照表、可复制配置片段、数字护栏（单供应商超时 30 秒、整轮预算 120 秒），以及可在租用 Apple Silicon Mac mini 上执行的清单——公开价约 ¥120/天（约 $16.9/天）。密钥卫生见 JSON 与环境变量 专文。
披露：MacHTML provides cloud Mac mini rental.
zai 供应商与模型 ID
OpenClaw 把智谱接入抽象为供应商 zai，模型引用写作 zai/<model-id>。面向代码与 HTML/CSS Agent 的默认选择是 zai/glm-5.1：工具调用与长上下文在网关侧与 Anthropic/OpenAI 路由共用同一套 JSON Schema，便于接入 模型故障转移 链。
不要把智谱 Key 写进 git 跟踪的 HTML 仓库；运行时只从 ~/.openclaw/.env 读取 ZAI_API_KEY，并对该文件执行 chmod 600（详见 JSON 与环境变量）。
onboarding：zai-api-key
首次在 macOS 上配置时，在终端执行 openclaw onboard，在供应商列表中选择 zai-api-key（或文档中的等价项）。向导会把密钥写入 ~/.openclaw/.env，并在 openclaw.json 中生成 providers.zai 占位，避免手工粘贴时误提交到 Slack 或工单。
在 open.bigmodel.cn 创建 Key 后，立刻在控制台为 Coding Plan 与通用 API 分别确认配额上限；财务侧应为 zai 单独设账单告警，避免与 Anthropic 共用同一预算标签。
onboarding 后立刻验证
- 确认
~/.openclaw目录权限为700，.env为600。 - 执行
openclaw doctor，确认providers.zai显示为已配置。 - 对
zai/glm-5.1发送一句合成对话，记录 latency 与 correlation id。
Coding Plan 与通用 API
智谱 Coding Plan 面向 IDE/Agent 高频工具调用，计费与限流与通用 GLM 对话 API 不同。OpenClaw 通过 zai-coding-cn（中国大陆 Coding 端点）与标准 zai 配置块区分流量——选错端点时常见症状是 403 或套餐外计费，而不是模型“变笨”。
| 场景 | 端点/配置 | 典型模型引用 |
|---|---|---|
| HTML/CSS Agent、工具密集 | zai-coding-cn | zai/glm-5.1 |
| 通用 Slack 摘要、只读问答 | 标准 zai | 按控制台可用 ID |
| 预发冒烟 | 与生产相同端点 | 与生产相同 ID |
字段名随 OpenClaw 版本迭代可能变化，部署前请对照 官方 GLM 文档 diff，勿盲目复制旧文片段。
openclaw.json 配置骨架
路由与供应商块放在 ~/.openclaw/openclaw.json，密钥仅通过环境变量注入。下面片段展示 zai/glm-5.1 作主模型、Coding 端点与超时护栏（结构仅供参考）：
{
"agents": {
"default": {
"model": {
"primary": "zai/glm-5.1",
"fallbacks": [
"anthropic/claude-sonnet-4-20250514"
]
}
}
},
"providers": {
"zai": {
"apiKey": "${ZAI_API_KEY}",
"endpoint": "zai-coding-cn",
"timeoutMs": 30000
}
}
}若未购买 Coding Plan，将 endpoint 改为文档中的标准 zai 值；两套端点不要在同一 Agent 上混用未文档化的字段。
ZAI_API_KEY 与环境变量
~/.openclaw/.env 示例：
ZAI_API_KEY=your_key_from_open_bigmodel_cnLaunchAgent 生产 plist 应通过 EnvironmentVariables 或登录 shell 加载同一文件，避免在 plist 内明文写 Key。轮换 Key 时：更新 .env → launchctl kickstart -k 网关 label → 再跑 doctor，无需重装 npm 包。
故障转移与 429 协同
智谱返回 429 时，仅在遵守 Retry-After 预算后切换到备用供应商；若备用与主模型工具 Schema 不一致，HTML/CSS 流水线会在半轮失败。热路径建议最多 三家供应商，并参考 429 重试专文 与 模型故障转移 设计备用链。
不要用“换更便宜模型”替代限流退避——Coding Plan 配额耗尽时，切到通用端点可能触发套餐外单价尖峰。
doctor 探针
每次修改 providers.zai 或 ZAI_API_KEY 后，执行 openclaw doctor --json 并把输出附在变更单。预发可暂时吊销 Key 的写权限（或使用只读 Key），确认 doctor 能在 10 秒内标出认证失败，而不是在生产频道沉默超时。
对 zai/glm-5.1 额外跑三条固定工具调用：读文件、写补丁、列目录——通过后再提升 LaunchAgent。
云 Mac mini 预发演练
在笔记本上练 GLM 路由常遇到与生产不一致的 Node 版本、Keychain 弹窗与家庭宽带上行瓶颈。租用 Apple Silicon Mac mini 可在与高管相同的 WebKit/macOS 构建上验证 zai-coding-cn 延迟：SSH 跑 doctor 与合成对话，需要 GUI 授权时用 VNC。
MacHTML 公开价约 ¥120/天（约 $16.9/天）：一周预发成本通常低于一夜“供应商认证错误”停摆。演练结束关机即可，openclaw.json 仍留在 git 忽略目录外的 ~/.openclaw。
大陆环境与 npm 痛点
大陆开发者常见摩擦包括：npm registry 访问慢、出口带宽 限制导致 openclaw 安装与模型 API 握手超时、以及公司代理对 open.bigmodel.cn 的 TLS 检查。建议在云 Mac 上固定 Node 22 LTS、配置镜像源，并对网关出口做 30 秒 超时与整轮 120 秒 上限，避免 Slack 线程“假死”。
不要把生产 ZAI_API_KEY 拷到个人笔记本做调试；使用独立预发 Key，并与生产 LaunchAgent 使用不同 plist label。
常见问题
Coding Plan 端点能和通用 GLM API 共用一把 Key 吗？
可以共用 ZAI_API_KEY，但 openclaw.json 里必须为 Coding 与通用流量选对配置块；混用端点会导致 403 或套餐外计费。
zai/glm-5.1 适合作为唯一生产模型吗？
适合代码 Agent 主路径，仍应配置 Schema 兼容的备用供应商，并在预发实测工具调用。
大陆笔记本上装 OpenClaw 要注意什么？
优先在云 Mac 上完成 npm 安装与 doctor；家庭宽带上行往往是瓶颈，而非 GLM 模型能力。
在真机 macOS 上配置 OpenClaw 智谱 GLM
租用云 Mac mini，在提升生产 LaunchAgent 之前验证 zai/glm-5.1、Coding Plan 端点与 doctor 探针。