OpenClaw GLM (Zhipu Z.AI) API on macOS in 2026: zai provider setup, Coding Plan endpoints, openclaw.json, and cloud Mac mini staging

Teams running OpenClaw on macOS in 2026 often add GLM—the model family on Z.AI (Zhipu’s API surface)—through the bundled zai provider. Use openclaw onboard --auth-choice zai-api-key, store ZAI_API_KEY in ~/.openclaw/.env, and set the default ref to zai/glm-5.1. If you purchased a Coding Plan, pin the endpoint with zai-coding-global or zai-coding-cn so traffic does not hit the general API quota by mistake. This guide follows the OpenClaw GLM provider docs and Z.AI platform, and links model failover, 429 retry, and doctor diagnostics so GLM is not a one-off experiment.

You will get a Coding Plan vs general API matrix, copy-ready openclaw.json skeleton, numeric guardrails (45 s per provider, 120 s per turn), and a staging checklist on a rented Apple Silicon Mac mini for about $16.9/day on published MacHTML pricing. Secrets hygiene is covered in JSON and environment profiles.

Disclosure: MacHTML provides the cloud Mac mini rental service referenced in this article.

zai provider and model refs

OpenClaw maps Zhipu to provider id zai with refs like zai/glm-5.1. The default text model supports reasoning and about 202k tokens of context per the bundled catalog. Vision tasks can target zai/glm-4.6v. Tool JSON schemas match other OpenAI-compatible providers, which simplifies failover chains.

Never commit API keys to git. Load ZAI_API_KEY from ~/.openclaw/.env with chmod 600 as described in JSON and environment profiles.

Onboarding: zai-api-key

openclaw onboard --auth-choice zai-api-key
openclaw config set agents.defaults.model.primary "zai/glm-5.1"
openclaw models list --provider zai

Explicit regional choices override auto-detection: zai-coding-global, zai-coding-cn, zai-global, zai-cn. Mainland keys often route to open.bigmodel.cn; global keys use https://api.z.ai/api/paas/v4.

Verify immediately after onboarding

1. chmod 700 ~/.openclaw and chmod 600 ~/.openclaw/.env.
2. openclaw doctor — confirm providers.zai is configured.
3. Synthetic chat to zai/glm-5.1; log latency and correlation id.

Coding Plan vs general API

Scenario	Auth choice	Typical ref
Agent / IDE tool-heavy	zai-coding-global or zai-coding-cn	zai/glm-5.1
General chat summaries	zai-global or zai-cn	Catalog-dependent
Staging smoke	Same as production	Same as production

Symptom: HTTP 429 with “insufficient balance” while Coding Plan quota remains—usually wrong endpoint surface. Re-run onboarding with the explicit zai-coding-* choice.

openclaw.json skeleton

{
  env: { ZAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "zai/glm-5.1",
        fallbacks: ["anthropic/claude-sonnet-4", "openai/gpt-4.1-mini"]
      }
    }
  },
  providers: { zai: { timeoutMs: 45000 } }
}

Diff field names against your installed OpenClaw release before paste-deploying.

ZAI_API_KEY and env files

Z_AI_API_KEY is accepted as an alias. Rotate keys by updating .env, then launchctl kickstart -k the gateway label, then rerun doctor—no npm reinstall required.

Failover and 429 coordination

Honor Retry-After before advancing to a secondary provider. Cap hot-path providers at three and total turn time near 120 seconds. See 429 retry and model failover.

Doctor probes

After every providers.zai or secret change, capture openclaw doctor --json on the change ticket. Run three canned tool calls—read file, write patch, list directory—before promoting LaunchAgent plists. Details: doctor diagnostics.

Cloud Mac mini staging

Staging on a rented Apple Silicon Mac mini matches production Node, Keychain, and WebKit behavior. SSH runs doctor and synthetic chats; use the help guide for access setup. Published MacHTML pricing near $16.9/day is usually cheaper than 36 months of idle CapEx during a one-week GLM routing drill.

FAQ

Can one ZAI_API_KEY serve both Coding Plan and general API?

Yes—pick the correct onboarding auth choice; mixing endpoints causes 403 or wrong quota buckets.

Should zai/glm-5.1 be the only production model?

Good for bilingual code agents; keep one schema-compatible fallback and smoke-test tools in staging.

Why stage on a cloud Mac instead of a laptop?

Home uplink and Node drift cause false negatives; a cloud Mac mirrors production LaunchAgent behavior.