刚打开 ZCode，很多人都会遇到同一个问题：输入框就在眼前，却不知道第一句话该写什么。让它直接做一个网站，担心需求说不清；打开已有项目，又怕代码被改乱。这篇 ZCode 使用教程就从实际操作出发，把下载安装、连接模型、打开项目、生成代码和检查结果串起来。即使之前没有接触过 AI 编程工具，也可以先跟着完成一个小页面，再慢慢处理复杂项目。
01｜ZCode是什么，适合用来做什么？
ZCode 是智谱推出的 AI 智能体开发环境，英文简称 ADE。它可以围绕本地项目读取文件、修改代码、执行命令，并协助完成调试、测试和变更审查。
理解它的用途，可以从一个具体任务开始：当你提出“给这个页面增加搜索功能”时，ZCode 可以先查看项目结构，找到相关文件，再根据要求修改代码，并尝试验证功能。
新手比较适合从以下三类任务入手：
制作简单页面： 例如个人主页、产品介绍页、活动报名页面。修改已有功能： 例如调整按钮样式、增加表单校验、修复布局错位。理解陌生项目： 让它解释目录结构、启动方式以及某段代码的作用。如果第一次使用就要求开发包含登录、支付和后台管理的完整系统，后续往往很难判断哪里出了问题。先完成一个能够打开、能够检查的小功能，会更容易掌握使用方法。
02｜下载安装ZCode，先选对系统版本
进入 ZCode 官方安装页面，根据电脑系统和处理器架构选择安装包。目前官方提供 Windows、macOS 和 Linux 版本。
Windows 用户： 下载对应安装程序，双击后按照向导完成安装，再通过开始菜单或桌面快捷方式启动。
macOS 用户： 注意区分 Apple Silicon 和 Intel 版本。打开下载的 DMG 文件后，将 ZCode 拖入 Applications 文件夹，再启动应用。
Linux 用户： 根据发行版选择合适的安装文件。使用 AppImage 时，需要先赋予文件可执行权限；使用 DEB 或 RPM 时，则通过对应的软件包管理器安装。
首次启动后，按照页面提示完成初始设置。没有旧数据需要导入，可以先跳过迁移，直接开始使用。软件界面会随版本更新，具体按钮名称以当前客户端为准。
03｜连接模型：账号登录和API Key怎么选？
第一次使用，优先考虑账号登录；已有模型服务密钥，再选择 API Key 接入。
按照官方连接文档，ZCode 支持连接 BigModel 或 Z.ai 账号。国内用户可以从 BigModel 入口开始，完成授权后，按照账号实际权益使用可用模型。
基本操作顺序如下：
在首次接入页面选择“连接 BigModel”或“连接 Z.ai”。按提示完成账号登录与授权。返回 ZCode，确认模型通道已经启用。在对话框的模型选择器中选择可用模型。发送一句简单指令，检查是否能够正常响应。进入应用后，也可以点击对话框中的模型名称，再从“管理模型”进入设置。
如果需要使用 API Key，则要核对接口地址、密钥和模型 ID。这三项必须与所选服务对应，不能随意拼凑。
这里有一个容易忽略的细节：Coding Plan 编程套餐与普通 API 余额使用的接口地址可能不同。 以 BigModel 的 OpenAI 兼容接口为例，官方文档分别列出了以下地址：
编程套餐：https://open.bigmodel.cn/api/coding/paas/v4通用 API：https://open.bigmodel.cn/api/paas/v4配置时应按自己的账号类型选择，其他供应商也要查阅对应说明。具体接入规则可以参考 ZCode 官方模型配置文档。
04｜打开项目，先让ZCode看懂当前目录
模型连接成功后，接下来需要选择工作区，也就是这次任务要操作的项目目录。
如果准备新建页面，可以先创建一个独立文件夹，例如“个人主页练习”，然后在 ZCode 中选择这个目录。若要修改现有项目，应打开项目根目录，让它能够看到说明文件、依赖配置和源代码。
第一次对话可以这样写：
请先查看当前目录，说明有哪些文件、项目使用什么技术、应该怎样启动。如果目录为空，请直接告诉我。暂时不要修改文件。
这一步既能检查模型和文件访问是否正常，也能避免在选错目录的情况下继续操作。
对于已有项目，开始修改前最好保存当前版本。有 Git 的项目可以先提交已有改动，没有使用版本管理的项目也可以先备份。这样即使后续效果不满意，也方便恢复。
05｜实操示例：用ZCode制作一个个人介绍页
第一次练习，可以选择不依赖后端服务的静态页面。需求越具体，生成结果越容易检查。
下面这段指令可以直接参考：
请在当前文件夹中制作一个个人介绍页，使用 HTML、CSS 和原生 JavaScript，不引入前端框架。页面包含姓名介绍、三个作品展示卡片和联系方式，整体采用白底深色文字，适配手机和电脑。点击作品卡片时展示对应介绍。请先简要说明文件安排，再创建页面，完成后告诉我如何在浏览器中打开和检查。
这段需求明确了技术范围、页面内容、交互方式和验收要求，比“帮我做一个好看的网站”更容易得到可用结果。
任务执行期间，留意它准备修改哪些文件、运行哪些命令。如果出现操作确认，先看清具体内容。页面生成以后，再按照提供的方式打开预览。
检查时重点看四件事：
页面能否正常打开，文字和图片是否完整。三个作品卡片是否都有内容。点击卡片后，介绍是否正确显示。缩小浏览器窗口后，页面是否出现横向溢出。如果效果需要调整，继续提出明确的小修改即可。例如：“手机端卡片之间的间距太大，请缩小间距，保留电脑端布局。”一次解决一个问题，通常比整页反复重做更好控制。
06｜修改代码时，怎样描述问题更有效？
使用 ZCode 处理已有项目时，最有用的信息通常是：哪里出问题、如何复现、实际结果是什么、希望改成什么样。
例如，页面按钮点击无效，可以这样描述：
在注册页面填写邮箱后点击提交，没有出现任何提示。请检查点击事件和表单校验逻辑，先说明原因，再做必要修改。不要调整页面样式，完成后给出验证步骤。
遇到报错，也不要只发一句“运行不了”。尽量提供报错原文、相关文件名，以及报错前执行的操作；日志中若包含密钥或个人信息，应先去除。
任务结束后，可以再补充一句：
请列出本次修改的文件、已经执行的检查，以及还需要我手动验证的部分。
这样更容易判断工作完成到了哪一步。尤其涉及登录、数据保存或接口调用时，不能只凭一句“已修复”就认定功能正常。
07｜ZCode使用中的常见问题
为什么配置完成后，模型仍然无法回复？
先检查所选通道是否启用，再核对账号权限、剩余额度和网络连接。使用 API Key 时，还要确认密钥有效、接口地址正确、模型 ID 与供应商要求一致。排查时一次只调整一项，避免改完后分不清原因。
为什么能生成代码，却启动不了项目？
代码生成和项目运行是两个环节。项目可能依赖 Node.js、Python 或其他运行环境，也可能需要安装依赖、补充配置。可以让 ZCode 根据项目文件说明启动条件，再逐项处理，不要在所有项目里套用同一条启动命令。
不会编程，也能使用ZCode吗？
可以从静态页面、简单脚本和小功能开始。你不必一开始就读懂全部代码，但需要能够描述需求，并检查结果是否符合预期。项目越复杂，越需要补充相应的开发知识。
ZCode是不是一直免费？
应以账号页面显示的体验权益和计费规则为准。官方文档提供了新用户限时体验说明，但体验额度不代表长期免费；接入第三方模型时，还要查看对应供应商的收费方式。