用 ZCode 桌面端接入 GLM-5.3 并跑通第一个 Agent 任务

ZCode 是一个把 GLM-5.3 带进真实编程工作流的 Agentic Development Environment（ADE）。它要解决的问题很具体：复杂开发任务往往横跨需求理解、计划拆解、改代码、跑验证、做 Review 好几个阶段，普通对话式工具每换一步就要重新交代背景，连续性很容易断。ZCode 的做法是把目标、文件、终端结果、浏览器上下文、执行模式和 Git 状态都保持在同一个任务里，让 Agent 从规划一路推进到实现与验证收口。它适合已经在用 GLM 系列模型、希望把长程任务交给桌面端 Agent 持续推进的开发者，也适合需要从手机端或聊天工具远程跟进长任务的人。本文按安装、首次启动、连接模型、跑通第一个任务、查看使用统计的顺序，把这条链路完整走一遍。如果你更习惯在浏览器里直接调用模型，可以先从 ZCode 相关的工具页了解入口，再回到桌面端做工程化操作。

准备工作

动手之前，先把下面几件事确认清楚，能省掉后面大半的排查时间。

系统与安装包

ZCode 桌面端支持以下平台，下载区按平台分别提供安装文件：

• macOS：Apple Silicon 与 Intel 两个版本，安装包为 .dmg 镜像。
• Windows：x64 与 ARM64 两个版本，提供安装程序。
• Linux：x64 与 ARM64，提供 .AppImage、.deb、.rpm 三种格式。

下载页会标出当前最新版本号，安装前建议确认自己拿到的是对应架构的包，尤其是 Apple Silicon 机器不要误装 Intel 版本。

账号与模型接入方式

ZCode 本身是客户端，真正干活的是背后的 GLM 模型。接入有三条路，任选其一：

• 连接 Z.ai：绑定 Z.ai 账号，使用内置的 GLM-5.3、GLM-5.3-Flash 等模型。
• 连接 BigModel：绑定 BigModel 账号，同样可以使用内置模型。
• 使用 API Key：不走账号登录，直接填入 API Key 完成接入。

如果你打算用 GLM Coding Plan 的套餐额度，需要绑定 Z.ai 或 BigModel 账号并连接对应的 Coding Plan。这一点在后面讲额度重置卡时还会再提到，因为它直接决定你能不能收到重置卡。

新用户额度

首次使用 ZCode 可以享受 5 天免费权益，开箱即用、无需额外配置。这 5 天内的每日额度为：

模型	每日额度
GLM-5.3	300 万 Token / 天
GLM-5-turbo	200 万 Token / 天
每日合计	500 万 Token

需要特别注意：这些额度只在首次使用的那 5 天内每日发放，5 天之后失效，并不是长期每天都有的固定配额。具体权益与额度以官网当前信息为准。

网络条件

如果你的网络需要走代理才能访问模型服务，提前准备好代理地址，例如 http://127.0.0.1:7890。企业内网如果部署了会解密 HTTPS 的安全网关，还要准备该网关签发根证书的 PEM 文件路径。这两项都在安装后的设置里配置，下面会详细讲。

操作步骤

第一步：安装桌面端

macOS

1. 打开下载的 ZCode.dmg 安装镜像。
2. 把 ZCode.app 拖动到 Applications 文件夹。
3. 在启动台中找到 ZCode 并启动。

Windows

1. 下载 ZCode 安装程序。
2. 双击运行，按安装向导完成安装。
3. 从开始菜单或桌面快捷方式启动。

Linux

1. 在下载区选择 Linux，下载 .AppImage、.deb 或 .rpm 安装文件。
2. AppImage 需要先加可执行权限，命令如下：

chmod +x ZCode-*.AppImage

使用 .deb 或 .rpm 时，通过发行版自带的软件包管理器安装即可。安装完成后双击文件或在终端中运行启动。

整个安装过程大约 2 分钟。

第二步：首次启动与工作区选择

首次启动会进入「首次启动设置」页面，流程如下：

1. 点击「开始使用 ZCode」直接进入。如果你需要迁移历史数据，可以选择「数据迁移向导」。目前迁移只支持导入 Claude Code 和旧版 ZCode 中 ZCode Agent 的对话记录，不支持其他工具。也可以先跳过，稍后在设置里继续迁移。
2. 进入后选择一个项目目录作为工作区。这个目录就是 Agent 后续读写文件、执行命令的范围，建议选一个你熟悉的、有版本控制的项目。
3. 在对话框输入一句简单指令，比如让 Agent 列出当前目录的文件，确认响应正常。

如果此时还没有配置模型，点击左下角的「连接使用」进入登录页面，按下一步完成接入。

第三步：连接模型

登录页面会引导你选择接入方式：连接 Z.ai、连接 BigModel，或使用 API Key。选择账号登录时，按页面提示完成授权即可；选择 API Key 时，把密钥填入对应输入框。接入完成后回到工作区，对话框就可以正常发起任务了。

如果你购买了 GLM Coding Plan，记得在接入时把账号与 Coding Plan 关联起来，否则使用统计里的「编程套餐」页读不到远端额度，也收不到额度重置卡。

第四步：配置网络代理（按需）

代理配置在「设置 → 常规」里，共有三个字段，填完点保存，需要重启应用才生效。

HTTP 代理：填入代理地址，例如：

http://127.0.0.1:7890

这里有一个很容易踩的坑：留空不等于跟随系统。该字段为空时 ZCode 直连，不会读取 HTTP_PROXY 等系统环境变量。这一点和很多命令行工具的默认行为相反。如果你发现终端里能联网而 ZCode 不行，多半就是这个原因。

配置之后，模型请求、MCP 服务、Agent 执行的命令工具以及应用界面的网络请求都会走这个代理。

代理例外：不想走代理的地址，用英文逗号分隔，例如：

localhost,127.0.0.1,::1,.example.com,*.corp.com

主机名、.example.com 这样的域名后缀、*.corp.com 通配写法都支持，需要时还能带上端口。

自定义证书：填 PEM 格式根证书的本地文件路径。企业内网如果用了会解密 HTTPS 的安全网关，它签发的证书默认不被信任，把对应的根证书填在这里即可。注意这不是跳过证书校验——ZCode 只放行证书链里确实包含这张根证书的连接，其余照常校验。

第五步：Windows 专属设置

如果你在 Windows 上使用，有两项设置值得单独确认。

命令行环境：在「设置 → 常规 → 终端」里可以指定 Agent 执行命令时用哪个 shell，可选「自动选择」、「CMD」和「Git Bash」（检测到已安装时才出现）。默认是自动，优先用 Git Bash，找不到就回退到 cmd.exe。改动只对新建会话生效，已有会话不会切换。

关闭窗口时最小化到托盘：从 v3.4.0 起这是默认行为。点窗口的关闭按钮不会退出应用，而是收进系统托盘继续运行，定时任务和闲时任务也因此能在后台照常推进。托盘图标右键有新建任务、打开工作区、检查更新、退出等菜单项，左键点击可以把窗口叫回来。

如果希望关闭按钮直接退出，在「设置 → 常规 → 通知」里关掉「关闭窗口时隐藏到托盘」即可。这个开关只有 Windows 有。从旧版本升级上来的用户请留意：这次默认值调整会把该开关重置为开启一次，即使你之前手动关过。再关一次之后就会一直保持你的选择。

一个完整示例

下面把前面几步串起来，走一遍从零到第一个任务跑通的最小流程。假设你使用的是 macOS Apple Silicon 机器，已有一个本地项目目录 ~/projects/demo。

1. 安装并启动

下载 ZCode.dmg，打开镜像，把 ZCode.app 拖进 Applications，然后在启动台启动。如果系统提示「ZCode 已损坏，无法打开」，在终端执行：

xattr -dr com.apple.quarantine /Applications/ZCode.app

执行后重新打开应用。

2. 完成首次启动设置

在「首次启动设置」页点击「开始使用 ZCode」。历史数据迁移这一步先跳过，后面需要时再在设置里做。

3. 选择工作区

把 ~/projects/demo 选为工作区。此后 Agent 的文件读写和命令执行都围绕这个目录展开。

4. 连接模型

点击左下角「连接使用」，在登录页选择「连接 Z.ai」并完成账号授权。如果你用的是 BigModel，就选「连接 BigModel」；如果手上只有 API Key，就选「使用 API Key」并填入密钥。接入完成后回到工作区。

5. 发一条验证指令

在对话框里输入一句简单指令，例如让 Agent 列出当前目录的文件。这一步的目的不是完成什么业务，而是确认三件事同时正常：模型能响应、工作区路径正确、命令执行链路通畅。如果 Agent 能正确列出 ~/projects/demo 下的文件，说明整条链路已经打通。

6. 推进一个真实任务

验证通过后，就可以用自然语言下达真实任务了。ZCode Agent 支持编码、调试、测试、项目预览和变更审查等工作。由于目标、文件、终端结果、执行模式和 Git 状态都保持在同一个任务里，你可以让它先给出计划，再逐步实施，中途补充指令而不必重新交代背景。关键命令、文件修改和高权限操作会在执行前进入确认流程，注意留意这些确认提示。

7. 核对用量

任务跑完后打开「使用统计」，确认消耗情况。这一页分两部分：

• 应用用量：统计当前设备上的 ZCode 会话记录，包括 Token 用量、会话数、消息数和活跃天数；当前连续使用天数、最长连续使用天数和峰值时段；按天 Token 趋势、活跃热力图和模型用量排行。按天趋势图支持悬停查看每日各模型的用量明细，下方模型用量环图汇总各模型的 Token 占比。右上角可以切换「全部时间」「最近 30 天」「最近 7 天」。
• 编程套餐：读取 Z.ai / BigModel Coding Plan 的远端统计，展示 5 小时 prompt 池、每周额度、MCP 每月额度等套餐状态，GLM-5.3、GLM-5.3-Flash 等模型的 Token 消耗，以及联网搜索 MCP、网页读取 MCP 等工具调用次数。点击或展开额度信息时，还能看到当前上下文窗口的组成、消息和工具调用占比，以及 5 小时、每周、工具调用等剩余额度。

如果你用的是 BigModel Coding Plan，同样可以在这一页查看对应的额度和消耗。

注意事项

额度与重置卡

5 小时额度或每周额度用完后，不一定要干等下一个周期。ZCode 3.8.1 及以上版本会在端内显示当前可用的 5 小时 / 每周额度重置机会，有重置机会时直接在端内点击即可重置对应额度。GLM Coding Plan 其他活动发放的重置卡也会在端内一并显示，使用方式相同。

重置卡只会下发给登录 ZCode 并连接了当前账号 Coding Plan 的用户。如果没有登录账号、只用 API Key 接入，或者登录的账号没有开通 Coding Plan（即使配置了 API Key），都不会收到重置卡。

使用统计的「编程套餐」页同样会显示可用的重置按钮，以及累计获得的重置次数。点击「重置」后，对应额度会立即恢复到 100%，并在卡片上标记「已重置」。

ZCode 会在闲时自动向 Coding Plan 用户下发 5 小时额度重置卡，需要同时满足三个条件：当前处于闲时时段、5 小时用量超过阈值、当日下发次数未达上限。注意重置卡的闲时时段与闲时任务的闲时范围不是同一套；具体时段和用量阈值都是动态调整的参数，以端内实际显示为准。下发后，输入框右下角会出现重置额度的提示。

重置卡有有效期，必须在有效期内使用，过期自动失效。点击重置按钮会弹出「可重置额度」面板，其中会列出每张卡的过期时间；有多张时，会自动使用最早获得的那张。

闲时任务

订阅用户可以创建「闲时任务」：把不着急的工作交给队列，ZCode 在算力富余时段免费完成，全程不消耗套餐额度。执行费用为免费，套餐额度消耗为 0。该功能面向订阅用户逐步开放。

常见安装问题

• macOS 提示「ZCode 已损坏，无法打开」：用前面给出的 xattr -dr com.apple.quarantine 命令解除隔离属性后重新打开。
• Windows 安装时被防火墙或杀软拦截：暂时关闭实时防护，或将安装目录加入白名单后重试。
• Linux 安装文件无法运行：确认已添加可执行权限（chmod +x）；部分发行版需要额外安装 fuse 依赖。

代理相关的两个易错点

第一，代理字段留空不会读取系统环境变量，必须显式填写。第二，自定义证书不是关闭证书校验，它只是把指定的根证书加入信任链，其余连接照常校验。企业内网环境下这两点经常被混淆。

多端协同

桌面端、手机端 Remote 与飞书 / 微信 Bot 可以共同推进同一个工作区任务。在长任务执行过程中，可以通过这些入口持续查看进度并补充指令。Bot 能力已接入飞书 / 微信，@ 一下即可让 ZCode Agent 远程触发并推进任务。

价格、套餐额度、功能开放范围等均可能调整，请以官网当前信息为准。