Install ZCode and Sign In

ZCode Beginner Path · Step 1

This opens the path, so it follows no previous step → this guide does one thing: install ZCode and sign in with a BigModel account.

🌟 Goal: get ZCode installed and signed in, clarify common installation checkpoints and the differences among the three sign-in options, laying the groundwork for the next three steps. It usually takes 5–10 minutes.

1. Download and Install ZCode

Open the ZCode website and download the version for your computer.

System	Installation
Windows	Download the Windows installer, open it, and follow the prompts
macOS	Open the .dmg file and drag ZCode into Applications
Linux	Choose AppImage, DEB, or RPM in the download section

If you are unsure which chip or package to choose, use the option recommended on the download page. See the ZCode installation documentation for details.

Why is a dedicated desktop client recommended for trade newcomers? Web-based AI chat interfaces can only converse within a browser tab. They cannot inspect local folders containing product photos, batch-rename quotation files, or run automated verification tools against web pages. Installing the desktop client allows the AI agent to operate within your trusted workspace, inspect project files, and deliver actionable results.

Common Installation Troubleshooting

When beginners install desktop developer tools for the first time, issues are almost always caused by operating system security policies rather than a corrupted package:

• Windows Defender or antivirus blocks the installer: Windows Defender or third-party antivirus software may flag newly released installers. This happens because freshly published software versions have not yet accumulated enough download telemetry in cloud reputation databases. As long as you downloaded the installer from the official website, click More info in the popup and then select Run anyway to proceed.
• macOS warns that the developer cannot be verified: macOS applies Gatekeeper notarization checks to apps downloaded outside the Mac App Store. If a prompt says the app cannot be opened, do not move the package to the Trash; open System Settings > Privacy & Security, scroll down to the Security section, click Open Anyway next to the notification, and confirm with your login password.
• Company office computers without admin privileges: Some company-managed laptops enforce strict IT group policies where opening .exe files requests an admin credential. Instead of force-closing repeatedly or searching for unauthorized patches, contact your internal IT administrator to help enter credentials or add ZCode to the approved software whitelist.
• Insufficient disk space or interrupted download: A corrupted installer typically causes extraction errors or prompts saying the file is damaged. Verify that your system drive has at least 5GB of free space, clear your browser download cache, and re-download the complete package from the official site.
• Previous installation residues causing conflicts: If an earlier test build was previously installed, leftover background processes might block writing new files. Open Task Manager on Windows or Activity Monitor on macOS, end any remaining ZCode background processes, and run the installer again.

If you encounter any of these situations, check the matching remedy before worrying about hardware compatibility.

2. Launch ZCode for the First Time

After installation:

1. Click Start Using ZCode.
2. Skip data migration if you have no previous data to import.
3. Continue to the sign-in page.

How to tell this step is correct: the welcome dialog displays the three sign-in options clearly, with Connect with BigModel visible in the center, free from freezing or blank screens.

Differences Between the Three Sign-In Options

On first launch, the welcome screen offers three sign-in methods:

• Z.ai Account: aimed at international portal accounts or dedicated overseas accounts. If your team registered an international workspace with an overseas business email, use this portal.
• BigModel Account (recommended first): the Zhipu open-platform account. Why first? It is the sign-in entry and the source of your GLM metered API Key (same provider — shortest path); no fiddly call parameters or network setup upfront.
• Use API Key: intended for technical users who already hold accounts with other model providers and want to configure custom endpoints. Beginners should avoid choosing this on day one, or you will get stuck having to find and configure an API key.

Key differences and selection guidance:

Sign-In Method	Best for	Why beginners should avoid	Billing and setup
BigModel (preferred)	Zero-experience exporters, tutorial students	Frictionless sign-up; the GLM metered API Key comes from this provider	Sign-in entry + API Key source, one stop
Z.ai	Global teams, international accounts	Domestic networks may experience latency; tailored to global accounts	Billed via separate international subscriptions
API Key	Experienced developers with existing keys	High risk of configuration errors with Base URLs and key permissions	Billed strictly per-token based on pay-as-you-go usage

The decision rule is simple: follow this tutorial and select BigModel. Only switch to an API Key later if you have specific models from other providers that you want to integrate.

3. Choose “Connect with BigModel”

On the welcome screen, click the middle option:

👉 Connect with BigModel

How to tell this step is correct: your system default web browser opens automatically to the official BigModel sign-in or authorization page. If no window appears, check if security software blocked external URL launches.

The authorization procedure takes only three simple steps:

1. Sign in to your BigModel account (register with your phone number or email if you do not have one yet).
2. Follow the prompt to confirm authorization and connect ZCode with your BigModel platform account.
3. Once authorization succeeds, the webpage will indicate completion and you can return to the ZCode client.

During browser authorization, the system securely passes authentication credentials back to ZCode via a local callback. Do not close the authorizing browser tab early until the page explicitly confirms authorization has succeeded.

4. Confirm That Sign-In Worked

After browser authorization, return to ZCode. Sign-in is complete when you reach the new-task or workspace screen and the sign-in choices no longer appear.

How to tell this step is correct: ZCode stays on the new task or workspace dashboard without falling back to the login options, with account information visible in the bottom-left corner.

For an extra check, open Settings → Model Settings from the lower-left gear icon and confirm that BigModel shows Enabled. Do not change the plan or model in this guide; Step 3 covers those settings.

How to tell this step is correct: inside Model Settings, the BigModel entry shows an Enabled badge and displays the account area properly.

Troubleshooting Empty Model Lists

Some beginners notice that after completing sign-in, clicking the model selection menu shows no available models and assume sign-in failed.

This is entirely normal: a freshly authorized account has no model connected yet. Model setup (recommended DeepSeek / GLM metered API, built-in plan as fallback) and everyday default assignments are all handled in Step 3 · Model Setup. An empty model list before setup is normal — not a broken app.

Why does this occur? Understanding the underlying authorization lifecycle helps avoid confusion:

1. Authentication phase (Step 1): establishes account credentials and verifies the connection between ZCode and the BigModel platform.
2. Capability grant phase (Step 2): grants operating system and tool control permissions so the AI can inspect files and execute tools.
3. Resource binding phase (Step 3): you explicitly choose your subscription plan and default model, which then pushes token quotas and active model lists down to the client interface.

If you have doubts at this step, keep these three checkpoints in mind:

• Checkpoint 1: Check Settings, not the prompt model dropdown. Seeing BigModel as Enabled in Model Settings means the authentication link is fully functioning.
• Checkpoint 2: Do not rush into random top-ups. Step 3 recommends the metered DeepSeek or GLM API — top up as needed and keep it controllable; ignore flashy other plans for now.
• Checkpoint 3: Keep your network active and continue. You do not need to reinstall or re-authorize; move straight to Step 2 to enable core capabilities.

📋 Installation Pitfalls

Pitfall	Consequence	How to avoid
🔴 Downloading from a non-official source	You may install a fake app or bundled adware	Download only from the ZCode website
🟡 Choosing the wrong sign-in option (Z.ai or API Key)	Your plan and models will not line up later, leaving you stuck at an API key prompt	Look for and choose Connect with BigModel in the center
🟡 Giving up when the OS security filter interrupts the installer	The software is never installed and your setup halts	On Windows, select "More info > Run anyway"; on macOS, go to "System Settings > Privacy & Security" and click "Open Anyway"
🟡 Assuming sign-in is broken because models do not appear yet	You waste time repeatedly uninstalling and reinstalling	Reaching the workspace completes this step; models and quota are configured in Step 3
🟢 Changing the model or plan at this step	You will switch back and forth in Step 3	Do not change settings here; Step 3 handles them

✅ Completion Check

• ZCode is installed and opens normally;
• You understand the three login paths and selected Connect with BigModel;
• Authorization returns you to the new-task or workspace screen;
• The sign-in choices no longer appear;
• Model Settings shows BigModel as Enabled.

📚 Further Reading

• 📚 Step 2 · Enable Core Capabilities: what comes next, so you know what to expect
• 📚 AI Tool Learning Path: what each of the four ZCode steps does
• 👉 ZCode installation documentation: official system requirements and installation notes

🚀 Next

📄 Step 2 · Enable Core Capabilities — turn on Full Access, Computer Control, Browser Control, memory, and indexing so ZCode can actually get to work.