如何安裝並設定 ZCode 搭配 GLM-5.3

ZCode 是 Z.ai 為 GLM-5.3 推出的官方編程 harness，桌面程式本身免費，但要讓它真的動起來，得把模型連上去。這段連接有幾種走法：用 Z.ai 帳號直接綁方案、用 API Key 手動設定，或接上第三方供應商。

這篇 ZCode 指南會完整說明如何使用 ZCode，從安裝一路帶到能跑第一個任務，包含 ZCode 設定最容易出錯的 Base URL 細節，以及怎麼用 ZCode Goal 模式把長任務交給它自己跑。

事前準備：ZCode 安裝前的確認事項

動手之前先確認三件事。

第一，作業系統版本。ZCode 目前提供 macOS、Windows 與 Linux 三種安裝檔，其中 Linux 仍標示為 Beta，版本已推進到 3.14 系列。如果你在 Linux 上部署，建議保留一份可回溯的舊版安裝檔。

第二，你要用哪種模型取用方式。最省事的是用 Z.ai 帳號綁定 GLM Coding Plan，額度跟著帳號走；另一條是自備 API Key，適合已經有自管模型管道的人。兩種方式的設定路徑不同。

第三，帳號準備。如果你打算走訂閱路線，先註冊 Z.ai 帳號並確認方案狀態；新帳號在綁定後會自動獲得試用額度，不需要先付款。

步驟 1：下載並安裝 ZCode

第一步是把程式裝起來。

1. 前往 ZCode 官方下載頁，挑選對應你作業系統的安裝檔。
2. 下載後執行安裝程式，依畫面指示完成安裝。
3. 首次啟動時，如果沒有任何可用的模型，歡迎畫面會直接提供連接選項。

這裡的路徑不需要猜。官方下載頁把每個平台、每個架構的安裝檔都列出來了，Linux 還分成 x64 與 ARM64 兩種，選錯架構會裝不起來，這點在 ARM 伺服器上特別容易踩到。

裝好之後先別急著開專案。下一步的模型連接沒設好，agent 是跑不動的。

步驟 2：用 Z.ai 帳號連接 GLM-5.3

這是絕大多數使用者該走的路，因為它最簡單，而且如果帳號本來就有 GLM Coding Plan，額度會直接套用。

1. 在首次啟動的歡迎畫面選擇「Continue with Z.ai」，或選「Continue with BigModel」用智譜帳號登入。
2. ZCode 會開啟授權流程，等供應商完成驗證後，帳號會自動綁定。
3. 進入 ZCode 後，點對話框裡的模型名稱開啟模型選擇器，再點最下方的「Manage Models」進入設定面板。
4. 在左側供應商列表選 Z.ai，連接帳號並打開啟用開關。
5. 在右上角的切換器選擇連接模式：綁定 GLM Coding Plan，或切換到 API Key 存取。

這裡有個容易忽略的地方：如果你是從對話框進入設定，模型選擇器要先點開才能看到 Manage Models，第一次用很容易找不到入口。

步驟 3：ZCode 設定 API Key 與 Base URL

如果你走的是 API Key 路線，這一步是整個流程最容易出錯的地方，因為端點填錯不會立刻報錯，只會出現奇怪的失敗。

先分清楚你的帳號類型，再填對應的網址。

如果是 GLM Coding Plan 的 API Key：

1. 在供應商頁面右上角把連接模式切到 API Key。
2. 把 OpenAI Base URL 設為 coding 專用端點 https://api.z.ai/api/coding/paas/v4。
3. 填入從 Z.ai 平台取得的 API Key。
4. Anthropic Base URL 則設為 https://api.z.ai/api/anthropic。

如果是模型資源包或預付餘額：

1. 連接模式同樣切到 API Key，但協議選 OpenAI。
2. OpenAI Base URL 設為一般端點 https://api.z.ai/api/paas/v4。
3. 填入 API Key。

官方文件特別標了一句：不要把 coding 專用端點換成一般端點。另外，資源包或預付餘額不要選 Anthropic 協定，因為 Anthropic 端點只對從未購買過 Coding Plan 的帳號從餘額扣款，一旦買過方案就不再走這條路。

步驟 4：加入其他供應商與模型

ZCode 的另一個價值是不綁死單一模型。要加其他供應商，流程都一樣。

1. 打開 Model Settings 面板。
2. 點供應商列表下方的「Add Provider」。
3. 為供應商命名，填入對應的 API base URL 與 API Key。
4. 儲存後點「Add Model」，輸入想用的模型 ID。
5. 打開啟用開關即可使用。

可接的選項包含 OpenAI、OpenRouter、Moonshot、MiniMax、Xiaomi MiMo，以及 Anthropic 的 Claude API。如果你想把 ZCode 當成統一入口，在不同任務間切換模型，這一步就是關鍵。

設定完成後記得儲存，回到對話框就能從模型切換選單挑到剛配置好的模型。

步驟 5：用 ZCode Goal 模式跑第一個長任務

模型接好之後，先別急著下複雜指令。跑一個小驗證，確認回應確實來自你要用的模型，再開始動真實專案。

確認沒問題之後，就可以試 ZCode Goal 模式，這是它最有代表性的功能。

1. 在對話框輸入 /goal 加一句目標，例如「重構這個模組並保持測試通過」。
2. 設定後，摘要面板會出現一張卡片，顯示目標與已經過的時間。
3. agent 會自己一輪一輪推進，每輪結束後另外跑一次驗證，沒達成就自動開始下一輪。
4. 過程中你可以用 /goal pause 暫停、/goal resume 恢復、/goal clear 清除。

目標寫得越具體可檢查，每輪判斷就越準。官方文件舉了很好的對照：讓 pnpm test 通過並保持首次繪製低於兩秒 遠勝過 讓它快一點。

有兩個情況會無法設定目標：在 Plan 模式下不行，因為它跟自動續跑的邏輯衝突；任務正在跑的時候也不行，得先等這一輪結束或先停止。

實用技巧：讓 ZCode 設定更順手

第一個技巧跟成本有關。GLM-5.3 的用量計費有非繁忙時段折扣，週一到週五新加坡時間 14:00 到 18:00 之外只按一半費率計算。把重度的 Goal 任務排在非繁忙時段或週末，用同一份訂閱能買到更多有效算力。

第二個技巧是排程與閒置任務。ZCode 支援設定時間規則、週期與到期日，也能讓任務在系統閒置時才跑。長時程任務搭配這個功能，等於自動避開繁忙時段。

第三個技巧是把首次跑的重度任務放在小範圍檔案上。先讓 agent 熟悉專案結構，再逐步擴大範圍，比一開始就丟整個 repo 穩得多。

第四個技巧是善用專案範圍記憶。ZCode 的記憶依專案組織，可以在設定裡瀏覽。同一個 repo 反覆作業時，這能省下大量重新交代背景的時間。

常見問題排查

連不上或跑不動時，先看這幾種情況。

授權失敗或 API Key 報錯：確認 Key 本身有效，且沒有被貼進提示詞或提交進版本庫。Coding Plan 的 Key 必須搭配 coding 專用端點，兩者要對應。

模型列表找不到 GLM-5.3：確認帳號權限與方案狀態。另外，如果你是用資源包或預付餘額，不要選 Anthropic 協定，改用 OpenAI 一般端點。

額度掉得比預期快：這是 GLM-5.3 詞元消耗偏高的必然結果。降低單次任務的上下文範圍、提高快取命中率、把任務排到非繁忙時段，都能有效減緩。

Goal 模式設定不了：確認目前不在 Plan 模式，且沒有任務正在執行中。

手機遠端連不上：手機只是控制面板，不會自己建立執行環境。桌面程式必須持續開著並保持連線，關掉視窗就接不上。另外遠端連結本身帶授權，用完要按 Stop，關掉對話框不算結束。

結語

走到這裡，你應該已經能在 ZCode 裡跑完整的代理式編程流程：安裝、連接 GLM-5.3、設定 API 端點、切換其他模型，最後用 Goal 模式把長任務交出去。

設定這套工具的門檻其實不高，最容易卡住的只有一個地方：API 端點與帳號類型必須對應。搞懂 coding 專用端點與一般端點的差別，其餘步驟都是照著做。

接下來比較值得花時間的是養成兩個習慣：把目標寫成可檢查的條件，以及把重型任務排到非繁忙時段。這兩件事直接決定你的體驗和帳單，比任何設定選項都更有影響。