ZCode 3.0 Guide: Install, Setup and First AI Task

Abstract

ZCode 3.0 is a desktop Agent-driven development environment developed by Zhipu. Compared with terminal-based Agent tools such as Claude Code and OpenCode, it delivers a streamlined deployment experience. Users only need to download an installer package and log into their accounts to get started. No Node.js environment configuration, manual API key creation or complex dependency management is required. This article offers a step-by-step walkthrough covering installation on macOS and Windows, initial setup, executing basic test tasks, and verifying Git integration capability. It also includes troubleshooting solutions for common installation and runtime errors. All hardware requirements, installation package sizes and free quota specifications from the original guide are fully preserved. For developers managing multiple AI coding agents and model endpoints, 4sapi serves as a unified API gateway to simplify cross-tool request routing and usage monitoring.

1 System Requirements

ZCode 3.0 supports macOS and Windows operating systems. It does not require a dedicated discrete graphics card or large memory allocation. Any computer capable of smoothly running VS Code can operate ZCode normally.

macOS

• Operating System: macOS 12 (Monterey) or newer
• Chip support: Native support for Apple Silicon (M1/M2/M3/M4), compatible with Intel architecture
• Installer size: Approximately 300 MB
• Disk occupation after installation: Less than 1 GB

Windows

• Operating System: Windows 10 Build 19041 or later (released after May 2020), full compatibility with Windows 11
• Architecture: x64 only
• Installer size: Approximately 250 MB

2 Download & Installation Procedures

2.1 macOS Installation

1. Open the Zhipu Open Platform, navigate to the ZCode product page, and select the macOS version download entry. The website automatically identifies your operating system and provides the corresponding .dmg installer file.
2. After downloading, double-click the .dmg file. Drag the ZCode icon into the Applications folder to complete installation.
3. When launching ZCode for the first time, macOS security restrictions will pop up a warning stating that ZCode is an application downloaded from the internet. Click Open to continue.
4. For enterprise-managed Mac devices, if MDM policies block installation, contact the internal IT team to whitelist the software. After installation, search for ZCode within Launchpad to launch the program.

2.2 Windows Installation

1. On the same download page, select the Windows version and download the .exe installer.
2. Double-click the installer and follow the default wizard prompts. Keep the default installation path: %LOCALAPPDATA%\Programs\ZCode. Do not change the path to a directory containing Chinese characters.
3. A desktop shortcut will be automatically generated after installation completes.
4. If corporate security software intercepts the installer, submit a whitelist request to the IT department. ZCode carries a valid digital signature and is not malicious software.

3 Account Registration and Login

Launch ZCode to enter the login interface. Two authentication methods are available:

1. Mobile Number Registration (Recommended for users in mainland China) Input your mobile number, obtain a verification code, set a password, and optionally bind your WeChat account. Binding WeChat facilitates multi-device login in the future.
2. WeChat Quick Login This method is only available if your existing Zhipu account has been bound to WeChat. New users must complete mobile registration first.

Once logged in successfully, the free token quota of 3,000,000 Tokens per day activates automatically. No extra application procedures, credit card binding or manual activation steps are needed. You can check your current cycle’s consumption and remaining allowance in the bottom-left corner or settings page. This quota satisfies the daily development needs of most individual developers.

4 Initial Configuration After First Login

After logging into the ZCode main interface, complete three core configuration steps to prepare for task execution.

4.1 Confirm Workspace Directory

ZCode uses your system Documents or user home directory as the default workspace. It is recommended to modify this path to your local project root folder. Set the workspace directory inside the settings panel, so newly created tasks can directly locate your code repository.

4.2 Learn the Grouped Task Panel Layout

The core interface of ZCode is the grouped task panel. The layout consists of three parts:

• Left sidebar: Project file tree
• Center area: Task dialogue window
• Right sidebar: Git graph and status overview

It is important to clarify that ZCode is an Agent-driven development environment rather than a traditional IDE. Familiarizing yourself with this layout helps improve long-term operational efficiency.

4.3 Adjust Automatic Approval Rules

By default, ZCode requires manual approval for every file modification and command execution. If you fully trust the current workspace, you can switch the approval mode from manual confirmation for every operation to automatic approval within the workspace in settings. New users should retain manual approval initially to observe all operations performed by the Agent before loosening permission controls.

5 Run Your First Verification Task

Avoid starting with complex engineering projects immediately. Deploy a simple test task to verify installation integrity and file access permissions.

Recommended Task: Build a Web Page Counter

This lightweight task requires no complex dependencies or configuration. It can be completed within several minutes, and results can be previewed directly in a browser. Enter the following instruction into the task dialogue box:

Help me create a simple web counter. Generate one HTML file with a clickable button that increments a numeric value. Keep the styling concise. Save the file under the workspace directory and return the file path after completion.

ZCode will not execute actions immediately. It first generates a complete execution plan listing all files to be created, code content and target directories. You need to review and approve the plan before the Agent starts working. During execution, ZCode automatically completes these steps:

1. Create the target HTML file
2. Write counter logic including UI buttons and number increment functions
3. Persist the file into the specified workspace directory
4. Output the final file path as a task summary

After the task finishes, open the generated HTML file via your system file manager and launch it in a browser. If the counter value increases normally upon clicking the button, your ZCode installation and permission configuration are fully functional.

6 Run Your First Git-enabled Task

The web counter task verifies basic file creation capabilities. Next, test native Git integration, one of ZCode’s differentiated features. Input the following task instruction:

Initialize a Git repository within the workspace, add the counter.html file you just created to version control, and make the initial commit. Create a new README.md file explaining the project purpose and running method. Commit the README file, then display the Git branch graph.

After execution, you can view two commit nodes and branch tracks on the right-side Git graph panel. This single task verifies three core capabilities: file creation, Git repository operation and version submission.

7 Troubleshooting Common Installation & Runtime Issues

Q: Application crashes immediately after opening

• macOS: Confirm your system version is macOS 12 or newer.
• Windows: Temporarily disable security software to rule out interception. If the crash persists, submit a support ticket via the user support page on the Zhipu Open Platform.

Q: System shows "Free quota not activated" after login

Check your network connection. If a proxy is enabled, disable it and log in again. The free token quota is allocated automatically. If activation fails continuously, log out and re-authenticate to trigger quota refresh.

Q: Task hangs indefinitely at "Analyzing requirements"

Network instability is the most frequent cause. Cancel the task and re-submit identical instructions. If the problem persists, inspect proxy settings. ZCode requires direct connectivity to Zhipu’s remote service endpoints, and proxy services may interfere with communication.

Q: Task execution returns "No file write permission"

Verify your workspace configuration. Confirm the target directory is included in the authorized directory list inside Settings → Workspace. All file operations are limited to approved paths for security isolation.

Q: Windows installer reports "Not a valid Win32 application"

You have downloaded the ARM64 installation package for an x64 Windows system, or vice versa. ZCode 3.0 currently only supports x64 architecture. Download the matching installer for your system architecture.

8 Summary

The complete deployment workflow for ZCode 3.0 can be condensed into three steps: download installer → log in and activate free token quota → run a simple test task for validation. The biggest advantage for domestic developers is zero extra configuration: no Node.js installation, no separate API key application, and no mandatory credit card binding. The daily free quota of 3 million tokens provides sufficient time to learn the tool without early charging pressure.

After successful installation, the next learning stage focuses on grouped multi-task workspaces, parallel task execution, context isolation between different tasks, and how visualized Git graphs support team collaboration.

If you encounter unusual error codes during installation, you can share your experience with other developers. As teams adopt multiple AI coding assistants alongside custom backend services, flexible traffic orchestration becomes essential. Many development teams leverage centralized routing tools such as 4sapi to manage all AI service endpoints in a unified way.