Providers

Z.AI

Z.AI는 GLM 모델용 API 플랫폼입니다. GLM용 REST API를 제공하며 인증에는 API 키를 사용합니다. Z.AI 콘솔에서 API 키를 생성하세요. OpenClaw는 Z.AI API 키와 함께 zai 제공자를 사용합니다.

속성 값
제공자 zai
패키지 @openclaw/zai-provider
인증 ZAI_API_KEY (레거시 별칭: Z_AI_API_KEY)
API Z.AI Chat Completions (Bearer 인증)

GLM 모델

GLM은 별도의 제공자가 아니라 모델 계열입니다. OpenClaw에서 GLM 모델은 zai/glm-5.2 같은 참조를 사용합니다. 제공자는 zai, 모델 ID는 glm-5.2입니다.

시작하기

먼저 제공자 Plugin을 설치합니다.

bash
openclaw plugins install @openclaw/zai-provider

엔드포인트 자동 감지

적합한 대상: 대부분의 사용자. OpenClaw는 API 키로 지원되는 Z.AI 엔드포인트를 조사하고 올바른 기본 URL을 자동으로 적용합니다.

  • 온보딩 실행

    bash
    openclaw onboard --auth-choice zai-api-key
  • 모델이 나열되는지 확인

    bash
    openclaw models list --all --provider zai
  • 명시적 지역 엔드포인트

    적합한 대상: 특정 Coding Plan 또는 일반 API 인터페이스를 강제로 사용하려는 사용자.

  • 올바른 온보딩 옵션 선택

    bash
    # Coding Plan 글로벌(Coding Plan 사용자에게 권장)openclaw onboard --auth-choice zai-coding-global # Coding Plan CN(중국 지역)openclaw onboard --auth-choice zai-coding-cn # 일반 APIopenclaw onboard --auth-choice zai-global # 일반 API CN(중국 지역)openclaw onboard --auth-choice zai-cn
  • 모델이 나열되는지 확인

    bash
    openclaw models list --all --provider zai
  • 엔드포인트

    온보딩 옵션 기본 URL 기본 모델
    zai-global https://api.z.ai/api/paas/v4 glm-5.1
    zai-cn https://open.bigmodel.cn/api/paas/v4 glm-5.1
    zai-coding-global https://api.z.ai/api/coding/paas/v4 glm-5.2
    zai-coding-cn https://open.bigmodel.cn/api/coding/paas/v4 glm-5.2

    zai-api-key는 각 엔드포인트의 채팅 완성 API에서 키를 조사하여 이 네 가지 중 하나를 자동으로 감지합니다. Coding Plan 엔드포인트(zai-coding-global, 이후 zai-coding-cn)보다 일반 엔드포인트(zai-global, 이후 zai-cn)를 먼저 확인하고, 요청을 수락하는 첫 번째 엔드포인트에서 중지합니다. 키가 두 유형 모두에서 작동하는 경우 Coding Plan 엔드포인트를 강제로 사용하려면 명시적인 --auth-choice를 사용하세요.

    구성 예시

    json5
    {  env: { ZAI_API_KEY: "sk-..." },  models: {    providers: {      zai: {        // GLM-5.2는 Coding Plan 엔드포인트를 사용합니다.        baseUrl: "https://api.z.ai/api/coding/paas/v4",      },    },  },  agents: { defaults: { model: { primary: "zai/glm-5.2" } } },}

    기본 제공 카탈로그

    zai 제공자 Plugin은 카탈로그를 Plugin 매니페스트에 포함하므로 읽기 전용 목록에서는 제공자 런타임을 로드하지 않고도 알려진 GLM 항목을 표시할 수 있습니다.

    bash
    openclaw models list --all --provider zai

    현재 매니페스트 기반 카탈로그에는 다음이 포함됩니다.

    모델 참조 참고
    zai/glm-5.2 Coding Plan 기본값, 1M 컨텍스트
    zai/glm-5.1 일반 API 기본값
    zai/glm-5
    zai/glm-5-turbo
    zai/glm-5v-turbo
    zai/glm-4.7
    zai/glm-4.7-flash
    zai/glm-4.7-flashx
    zai/glm-4.6
    zai/glm-4.6v
    zai/glm-4.5
    zai/glm-4.5-air
    zai/glm-4.5-flash
    zai/glm-4.5v

    사고 수준

    GLM-5.2

    전체 범위는 off, low, high, max이며 기본값은 off입니다. OpenClaw는 요청 페이로드의 reasoning_effort를 통해 low와 high를 Z.AI의 high 추론 강도로, max를 Z.AI의 max 강도로 매핑합니다.

    기타 GLM 모델

    이진 전환만 지원합니다. off와 low(선택 도구에서는 on으로 표시)이며 기본값은 off입니다. 사고를 off로 설정하면 thinking: { type: "disabled" }를 전송합니다. 그 외 수준에서는 요청 페이로드를 변경하지 않으며 Z.AI 자체의 기본 추론 동작이 적용됩니다.

    사고를 off로 설정하면 표시되는 텍스트보다 먼저 reasoning_content에 출력 예산을 소비하는 응답을 방지할 수 있습니다.

    고급 구성

    알 수 없는 GLM-5 모델의 순방향 확인

    알 수 없는 glm-5* ID도 현재 GLM-5 계열 형식과 일치하면 glm-4.7 템플릿에서 제공자 소유 메타데이터를 합성하여 제공자 경로에서 계속 순방향으로 확인됩니다.

    도구 호출 스트리밍

    Z.AI 도구 호출 스트리밍에서는 tool_stream이 기본적으로 활성화됩니다. 비활성화하려면 다음과 같이 설정합니다.

    json5
    {  agents: {    defaults: {      models: {        "zai/<model>": {          params: { tool_stream: false },        },      },    },  },}
    사고 내용 보존

    Z.AI에서는 전체 과거 reasoning_content를 다시 재생해야 하며 이로 인해 프롬프트 토큰이 증가하므로 사고 내용 보존은 명시적으로 활성화해야 합니다. 모델별로 활성화하세요.

    json5
    {  agents: {    defaults: {      models: {        "zai/glm-5.2": {          params: { preserveThinking: true },        },      },    },  },}

    활성화된 상태에서 사고 기능이 켜져 있으면 OpenClaw는 thinking: { type: "enabled", clear_thinking: false }를 전송하고 동일한 OpenAI 호환 대화 기록에 대해 이전 reasoning_content를 다시 재생합니다. 스네이크 케이스인 preserve_thinking 매개변수 키도 별칭으로 작동합니다.

    고급 사용자는 params.extra_body.thinking을 사용하여 정확한 제공자 페이로드를 계속 재정의할 수 있습니다.

    이미지 이해

    Z.AI Plugin은 이미지 이해 기능을 등록합니다.

    속성 값
    모델 glm-4.6v

    이미지 이해 기능은 구성된 Z.AI 인증에서 자동으로 확인되므로 추가 구성이 필요하지 않습니다.

    인증 세부 정보
    • Z.AI는 API 키를 사용하는 Bearer 인증을 사용합니다.
    • zai-api-key 온보딩 옵션은 키로 지원되는 엔드포인트를 조사하여 일치하는 Z.AI 엔드포인트를 자동으로 감지합니다.
    • 특정 API 인터페이스를 강제로 사용하려면 명시적인 지역 옵션(zai-coding-global, zai-coding-cn, zai-global, zai-cn)을 사용하세요.
    • 레거시 환경 변수 Z_AI_API_KEY도 계속 허용됩니다. ZAI_API_KEY가 설정되지 않은 경우 OpenClaw는 시작 시 해당 값을 ZAI_API_KEY로 복사합니다.

    관련 문서

    Was this useful?
    On this page

    On this page