2026년 macOS OpenClaw: GLM(zai) 프로바이더, ZAI_API_KEY, Coding Plan, doctor, 서울 노드 클라우드 Mac mini

2026년, Anthropic·OpenAI 옆에 비용 효율적인 이중언어 LLM을 두려는 운영자는 Zhipu 글로벌 API 표면인 Z.AI의 GLM을 검토합니다. macOS의 OpenClaw에서는 별도 미스터리 프로바이더가 아니라 번들 zai 런타임으로 제공되며, zai/glm-5.1 ref, OpenAI 호환 HTTP, Coding Plan 대 일반 API 온보딩 선택이 있습니다. 이 글은 ZAI_API_KEY, openclaw.json, 모델 페일오버, JSON·환경 프로필, 429 재시도, doctor 진단과 함께 검증하는 방법을 설명합니다.

고지: 이 글에서 언급하는 클라우드 Mac mini 임대 서비스는 MacHTML이 제공합니다.

MacHTML 서울 노드의 Apple Silicon Mac mini(공개 요금 하루 약 $16.9)에서 프로덕션과 동일한 Node·Keychain 동작으로 GLM을 스테이징할 수 있습니다. 공식 참고: OpenClaw GLM 프로바이더 문서.

OpenClaw에서 GLM을 쓰는 이유

GLM은 한·영 혼합 에이전트 턴, 긴 컨텍스트 추론, 배치 작업 가격대에 강합니다. OpenClaw는 zai로 다른 OpenAI 호환 프로바이더와 같은 도구 호출 경로를 유지합니다. 클라우드 Mac mini에서는 보통 다음 3가지입니다.

1. 한·중 혼합 채널의 프라이머리
2. Anthropic 429 이후 세컨더리(별도 쿼터)
3. 텍스트 전용 프라이머리일 때 zai/glm-4.6v 비전

zai 프로바이더 사실

항목	값
프로바이더 ID	zai
인증	ZAI_API_KEY 또는 Z_AI_API_KEY
기본 base URL	https://api.z.ai/api/paas/v4
권장 모델	zai/glm-5.1
기본 이미지 모델	zai/glm-4.6v
API 형태	OpenAI 호환

중국 본토는 https://open.bigmodel.cn/api/paas/v4가 일반적입니다. OpenClaw zai-cn / zai-coding-cn 온보딩으로 올바른 쿼터 버킷에 고정하세요.

온보딩과 시크릿

API 키를 git에 커밋하지 마세요. ~/.openclaw/.env에 두고 chmod 600을 적용합니다.

# 키 형태로 엔드포인트 자동 감지
openclaw onboard --auth-choice zai-api-key

# Coding Plan (글로벌)
openclaw onboard --auth-choice zai-coding-global

# Coding Plan (중국)
openclaw onboard --auth-choice zai-coding-cn

# 카탈로그 확인
openclaw models list --provider zai

# 기본 모델
openclaw config set agents.defaults.model.primary "zai/glm-5.1"

시크릿·라우팅 변경 후마다 openclaw doctor를 실행하세요.

openclaw.json 골격

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

필드명은 릴리스마다 바뀔 수 있습니다. 붙여넣기 전 설치된 OpenClaw 버전과 diff하세요.

Coding Plan vs 일반 API

auth-choice	용도
zai-api-key	키로 엔드포인트 자동 감지
zai-coding-global	Coding Plan (글로벌)
zai-coding-cn	Coding Plan (중국)
zai-global	일반 API (글로벌)
zai-cn	일반 API (중국)

증상: Coding Plan 잔액이 있는데 HTTP 429와 «잔액 부족»— 대개 일반 API로 트래픽이 간 경우입니다. /api/coding/paas/v4가 아닌 일반 엔드포인트일 수 있으므로 zai-coding-*로 다시 온보딩하세요.

모델 카탈로그

openclaw models list --provider zai로 라이브 목록을 확인합니다. 2026년 대표 ref:

모델 ref	용도
zai/glm-5.1	기본 추론, 202k 컨텍스트
zai/glm-5v-turbo	추론 + 이미지 입력
zai/glm-4.7-flash	저지연 내부 봇
zai/glm-4.6v	기본 비전 모델

페일오버 체인에서는 프로바이더당 약 45초, 턴 전체 약 120초 상한을 권장합니다.

페일오버와 도구 호환

체인의 GLM은 프라이머리와 동일 JSON 도구 스키마를 받아야 합니다. 프로덕션 승격 전 zai/glm-5.1에 읽기·쓰기·목록 3종 도구 호출을 스테이징에서 실행하세요. 텍스트 전용 GLM으로 페일오버할 때는 이미지 파트를 제거하세요. 자세히는 모델 페일오버 글을 참고하세요.

macOS 스테이징 체크리스트

1. 시크릿 없는 openclaw.json 핑거프린트를 git 밖으로 보내기
2. 올바른 지역 auth-choice로 zai 온보딩
3. openclaw models list --provider zai — GLM 행 1개 이상
4. 스테이징 포트에서 합성 채팅 + 도구 스모크
5. 프라이머리 장애 시뮬레이션, 10초 내 GLM 응답 확인
6. 24시간 클린 메트릭 후 LaunchAgent 승격

서울 노드 MacHTML 임대 Mac mini(약 $16.9/일)는 Linux 심이 아닌 프로덕션과 같은 macOS에서 GLM을 검증합니다.

FAQ

GLM과 Zhipu 회사명이 같나요?

아닙니다. GLM은 모델 패밀리이고, 결제·키는 Z.AI / BigModel에서 관리됩니다.

어떤 환경 변수를 쓰나요?

ZAI_API_KEY를 권장합니다. Z_AI_API_KEY도 별칭으로 허용됩니다.

GLM이 파괴적 도구의 Anthropic 대체가 되나요?

도구 스키마 스모크와 human-in-the-loop 정책 검토 후에만 가능합니다.

doctor 실행 빈도는?

zai 시크릿·엔드포인트·기본 모델 변경 시마다, 프로덕션에서는 주 1회입니다.