OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

Z.AI

Z.AI adalah platform API untuk model GLM. Platform ini menyediakan REST API untuk GLM dan menggunakan kunci API untuk autentikasi. Buat kunci API Anda di konsol Z.AI. OpenClaw menggunakan penyedia zai dengan kunci API Z.AI.

Properti Nilai
Penyedia zai
Paket @openclaw/zai-provider
Autentikasi ZAI_API_KEY (alias lama: Z_AI_API_KEY)
API Penyelesaian Percakapan Z.AI (autentikasi Bearer)

Model GLM

GLM adalah keluarga model, bukan penyedia terpisah. Di OpenClaw, model GLM menggunakan referensi seperti zai/glm-5.2: penyedia zai, id model glm-5.2.

Memulai

Instal Plugin penyedia terlebih dahulu:

bash
openclaw plugins install @openclaw/zai-provider

Deteksi endpoint otomatis

Paling cocok untuk: sebagian besar pengguna. OpenClaw memeriksa endpoint Z.AI yang didukung dengan kunci API Anda dan menerapkan URL dasar yang benar secara otomatis.

  • Jalankan orientasi awal

    bash
    openclaw onboard --auth-choice zai-api-key

  • Verifikasi bahwa model tercantum

    bash
    openclaw models list --all --provider zai

    • Endpoint regional eksplisit

    Paling cocok untuk: pengguna yang ingin memaksakan Coding Plan tertentu atau permukaan API umum.

  • Pilih opsi orientasi awal yang tepat

    bash
    # Coding Plan Global (direkomendasikan untuk pengguna Coding Plan)openclaw onboard --auth-choice zai-coding-global # Coding Plan CN (wilayah Tiongkok)openclaw onboard --auth-choice zai-coding-cn # API umumopenclaw onboard --auth-choice zai-global # API umum CN (wilayah Tiongkok)openclaw onboard --auth-choice zai-cn

  • Verifikasi bahwa model tercantum

    bash
    openclaw models list --all --provider zai

    • Endpoint

    Opsi orientasi awal URL dasar Model default
    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

    Z.AI juga memublikasikan URL dasar Coding Plan yang kompatibel dengan Anthropic https://api.z.ai/api/anthropic. Opsi Z.AI OpenClaw menggunakan endpoint Penyelesaian Percakapan OpenAI yang didokumentasikan di atas; URL Anthropic ditujukan bagi klien yang berkomunikasi langsung menggunakan Pesan Anthropic.

    zai-api-key mendeteksi secara otomatis salah satu dari empat endpoint ini dengan menguji kunci Anda terhadap API penyelesaian percakapan setiap endpoint, memeriksa endpoint umum (zai-global, lalu zai-cn) sebelum endpoint Coding Plan (zai-coding-global, lalu zai-coding-cn), dan berhenti pada endpoint pertama yang menerima permintaan. Gunakan --auth-choice eksplisit untuk memaksakan endpoint Coding Plan jika kunci Anda berfungsi pada keduanya.

    Batas laju dan kelebihan beban

    Z.AI mendokumentasikan Coding Plan dan alat agen serbaguna sebagai layanan dengan kapasitas terkelola. Dalam dokumentasi Z.AI sendiri:

    • Alat agen serbaguna, termasuk OpenClaw, dilayani atas dasar upaya terbaik. Selama beban inferensi tinggi, biasanya sekitar pukul 14.00–18.00 waktu Singapura, beberapa permintaan mungkin mengalami batas laju sementara.
    • Batas laju dan konkurensi Coding Plan terkait dengan tingkatan paket dan dapat disesuaikan secara dinamis berdasarkan ketersediaan sumber daya. Jam sepi mungkin memiliki konkurensi yang lebih tinggi.
    • Kode kesalahan API 1302 berarti "Batas laju untuk permintaan telah tercapai". Kode kesalahan API 1305 berarti "Layanan mungkin mengalami kelebihan beban sementara, silakan coba lagi nanti".

    Jika Anda melihat respons sementara 429 atau 1305 selama periode sibuk, tunggu dan coba ulang permintaan. Jika kegagalan terus berulang di luar periode puncak, atau hanya terjadi pada satu endpoint, model, atau bentuk permintaan, periksa terlebih dahulu endpoint dan model yang dikonfigurasi:

    bash
    openclaw models list --all --provider zaiopenclaw config get models.providers.zai.baseUrl

    Kunci Coding Plan harus menggunakan endpoint Coding Plan seperti https://api.z.ai/api/coding/paas/v4; kunci API umum harus menggunakan endpoint API umum seperti https://api.z.ai/api/paas/v4. Kegagalan terus-menerus dengan kunci dan endpoint yang sama dapat menunjukkan penolakan dari sisi penyedia atau pembatasan paket, bukan pembatasan laju biasa akibat beban puncak.

    Contoh konfigurasi

    json5
    {  env: { ZAI_API_KEY: "sk-..." },  models: {    providers: {      zai: {        // GLM-5.2 menggunakan endpoint Coding Plan.        baseUrl: "https://api.z.ai/api/coding/paas/v4",      },    },  },  agents: { defaults: { model: { primary: "zai/glm-5.2" } } },}

    Katalog bawaan

    Plugin penyedia zai menyertakan katalognya dalam manifes Plugin, sehingga daftar hanya-baca dapat menampilkan baris GLM yang diketahui tanpa memuat runtime penyedia:

    bash
    openclaw models list --all --provider zai

    Katalog berbasis manifes saat ini mencakup:

    Referensi model Catatan
    zai/glm-5.2 Default Coding Plan; konteks 1M
    zai/glm-5.1 Default API umum
    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

    Metadata biaya token katalog mengikuti harga bayar sesuai pemakaian Z.AI saat ini. Langganan Coding Plan menggunakan kuota paket alih-alih penagihan per token; lihat halaman langganan langsung untuk harga dan ketersediaan paket.

    Tingkat pemikiran

    GLM-5.2

    Rentang lengkap: off, low, high, max (default off). OpenClaw memetakan low dan high ke upaya penalaran high Z.AI, serta max ke upaya max Z.AI, melalui reasoning_effort pada muatan permintaan.

    Model GLM lainnya

    Hanya pengalih biner: off dan low (ditampilkan sebagai on dalam pemilih), default off. Mengatur pemikiran ke off akan mengirim thinking: { type: "disabled" }; tingkat lainnya membiarkan muatan permintaan tidak berubah (perilaku penalaran default Z.AI sendiri berlaku).

    Mengatur pemikiran ke off menghindari respons yang menghabiskan anggaran keluaran untuk reasoning_content sebelum teks yang terlihat.

    Konfigurasi lanjutan

    Resolusi maju model GLM-5 yang tidak dikenal

    Id glm-5* yang tidak dikenal tetap diresolusikan secara maju pada jalur penyedia dengan menyintesis metadata milik penyedia dari templat glm-4.7 ketika id cocok dengan bentuk keluarga GLM-5 saat ini.

    Streaming pemanggilan alat

    tool_stream diaktifkan secara default untuk streaming pemanggilan alat Z.AI. Untuk menonaktifkannya:

    json5
    {  agents: {    defaults: {      models: {        "zai/<model>": {          params: { tool_stream: false },        },      },    },  },}
    Pemikiran yang dipertahankan

    Pemikiran yang dipertahankan bersifat pilihan karena Z.AI mengharuskan seluruh reasoning_content historis diputar ulang, yang meningkatkan token prompt. Aktifkan per model:

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

    Saat diaktifkan dan pemikiran menyala, OpenClaw mengirim thinking: { type: "enabled", clear_thinking: false } dan memutar ulang reasoning_content sebelumnya untuk transkrip kompatibel OpenAI yang sama. Kunci parameter snake_case preserve_thinking berfungsi sebagai alias.

    Pengguna tingkat lanjut tetap dapat mengganti muatan penyedia secara persis dengan params.extra_body.thinking.

    Pemahaman gambar

    Plugin Z.AI mendaftarkan pemahaman gambar.

    Properti Nilai
    Model glm-4.6v

    Pemahaman gambar diresolusikan secara otomatis dari autentikasi Z.AI yang dikonfigurasi — tidak diperlukan konfigurasi tambahan.

    Detail autentikasi
    • Z.AI menggunakan autentikasi Bearer dengan kunci API Anda.
    • Opsi orientasi awal zai-api-key mendeteksi secara otomatis endpoint Z.AI yang cocok dengan menguji endpoint yang didukung menggunakan kunci Anda.
    • Gunakan opsi regional eksplisit (zai-coding-global, zai-coding-cn, zai-global, zai-cn) ketika Anda ingin memaksakan permukaan API tertentu.
    • Variabel lingkungan lama Z_AI_API_KEY masih diterima; OpenClaw menyalinnya ke ZAI_API_KEY saat mulai berjalan jika ZAI_API_KEY belum ditetapkan.

    Terkait

    Pemilihan model

    Memilih penyedia, referensi model, dan perilaku failover.
    Referensi konfigurasi

    Skema konfigurasi lengkap OpenClaw, termasuk pengaturan penyedia dan model.
    Was this useful?
    On this page

    On this page