夜雨聆风关注◆ AI一手 ◆探索AI时代的一手实战玩法
最近 Claude 封号封得越来越狠了，身边不少朋友的号说没就没。
搞得很多人开始重新看国内的替代方案。
然后就注意到了 GLM-5.2，智谱最新的旗舰模型。
这个模型在 Design Arena 编程排行榜上直接干到了第一名，部分能力已经接近甚至超过 Fable 5，但 API 价格只有 Fable 的七分之一到十分之一左右。
而 ZCode，就是智谱围绕这个模型做的 Agent 编程工具。
我在智谱官方 X 账号上看到最新的 3.x 版本已经发布了，不用折腾网络、不用海外信用卡、不用担心哪天起来号没了，国内账号直接用。
所以今天这篇，就基于这个最新版本，从零开始把 ZCode 的上手流程讲透。从下载安装到配模型、跑第一个任务、读老项目、修 Bug、用 Goal Mode 跑长任务，每步告诉你点哪里、填什么、正常会看到什么、出了问题怎么办。
0 先说结论，ZCode 适合谁
你可能听过 Cursor、Windsurf、Claude Code 这些 AI 编程工具。说实话，2026 年这个时间点，这几家都已经有 Agent 模式了，都能读项目、改代码、跑命令。
功能层面，这几家工具的能力已经高度趋同了，Agent 模式、多模型支持、远程控制、长任务自动迭代，大家基本都有。
ZCode 对国内用户最大的吸引点就是省心。国内账号直接登录，原生接 GLM-5.2，不用折腾网络和海外支付，不用担心封号。
小白能不能用？ 能。你不需要会写代码，不需要懂命令行。装好软件、配好模型，用中文告诉它你要什么就行。但你至少要能看懂它的操作，知道什么时候该点确认、什么时候该拒绝。
老开发值不值得试？ 如果你已经在用 Cursor 或 Claude Code 并且用得很顺，功能层面 ZCode 没有什么独占的东西，不用特意切换。但如果你一直被账号和网络问题折腾，或者想试试 GLM-5.2 在编程场景下的表现，ZCode 是目前最方便的入口。
1 国内用户和海外用户，先搞清楚走哪个通道
这是很多人第一步就踩的坑。ZCode 有两个主要的模型接入通道，填错了可能能连上但额度不生效。
海外用户 走 Z.ai 通道。官网是 https://z.ai ，价格标的是美元。
国内用户 走 BigModel / 智谱开放平台通道。官网是 https://bigmodel.cn ，价格标的是人民币。
一个最简单的判断方法，你打开页面后先看价格单位。如果是美元，那就是海外 Z.ai 通道。如果你人在国内，优先确认 BigModel 智谱开放平台的入口。
两个通道的订阅、账号、额度、模型接入方式不完全一样，不要混着配。
2 下载安装
ZCode 支持 macOS、Windows 和 Linux（Linux 目前还在 beta）。
去官网 https://zcode.z.ai 点首页的下载按钮，它会自动识别你的系统给你推荐对应版本。
Windows
点 Download ZCode，选择 Windows x64（如果你的电脑是 ARM 架构选 Windows ARM64，不确定就选 x64，绝大多数 Windows 电脑都是） 
下载安装包，双击运行 
跟着安装向导一路下一步 安装完成后，开始菜单或桌面会出现 ZCode 图标 双击打开，看到欢迎页面说明安装成功
打不开怎么办 如果系统弹出安全风险提示，点「更多信息」再点「仍要运行」。如果下载速度很慢，可以试试换个浏览器或者换个时间段下载。
macOS
先确认你的芯片类型。点左上角苹果图标 → 关于本机，看到 M1/M2/M3/M4 就是 Apple Silicon，看到 Intel 就是 Intel 下载对应版本的 DMG 文件 双击打开 DMG，把 ZCode.app 拖到 Applications 文件夹 
从 Launchpad 启动 
第一次打开提示「无法验证开发者」怎么办 去系统设置 → 隐私与安全性，拉到最下面，会看到「已阻止 ZCode」，点旁边的「仍要打开」。
Linux
官方目前 Linux 版还是 beta 状态。如果你用 Linux 做主力开发，可以去官网申请 beta 资格，或者先用 macOS / Windows 版本。以官方后续更新为准。
3 第一次打开 ZCode 后，先做什么
第一次打开 ZCode，如果还没有可用模型，欢迎页通常会给你三个入口。
连接 BigModel 国内用户优先选这个，直接用智谱开放平台的账号登录。
连接 Z.ai 海外用户优先选这个，走 Z.ai 通道。
使用 API Key 适合自己接第三方模型的人，比如 Claude、DeepSeek、Moonshot 等。
有一点要搞清楚，ZCode 这个软件本身是免费的，下载安装不花钱。但是真正帮你干活的是后面的 AI 模型，模型调用是要花钱的，需要订阅 GLM Coding Plan、充值 API 余额、或者用第三方模型的 API Key。
没有配模型的话，ZCode 打开了也干不了活。
4 配置模型，三条路线选一条
这一步决定了你能用什么模型。不同路线的复杂度不一样，按自己的情况选。
小白路线，官方通道直连
最省心的方式。
国内用户 去 https://bigmodel.cn/glm-coding 注册账号，订阅 GLM Coding Plan。有三个档位（截至 2026 年 7 月）
Lite 档，适合个人轻度使用，5 小时内约 80 次对话，每周约 400 次。
Pro 档，适合日常开发，5 小时内约 400 次对话，每周约 2000 次。
Max 档，适合重度使用，5 小时内约 1600 次对话，每周约 8000 次。
不过国内这个订阅比较难抢，大家要每天上午10点准时去抢。
订阅完之后，回到 ZCode，有两种方式连接。
方式 A 在欢迎页面或设置里选「BigModel」Provider，登录你的智谱账号，绑定后自动关联套餐。
方式 B 手动配 API Key。 有两种界面： 1、欢迎页选择「BigModel」选项 → 输入对应的国内的apikey，也可以点击暂时跳过，进入到模型设置界面。
其他国内大模型选择添加供应商。
2、点聊天框里的模型名称 → 选「管理模型」→ 左侧默认（根据欢迎页设置选择来）→ 填入 API Key。这里如果你之前用了方式A登录过你国内的账号了，那么你直接可以点击断开连接：
这样你就又进入到刚开始打开的那个界面
继续用新的方式B来配置你的模型了，可以点击暂时跳过按钮。
海外用户 去 https://z.ai/subscribe 订阅 GLM Coding Plan，在 ZCode 里选「Z.AI」Provider 登录即可。
所有套餐都支持 GLM-5.2、GLM-5-Turbo、GLM-4.7 这些模型。
有个额度细节要注意，GLM-5.2 和 GLM-5-Turbo 是高阶模型，高峰期（每天 14:00-18:00 UTC+8）调用按 3 倍消耗额度，非高峰期按 2 倍。目前有个限时优惠，非高峰期只算 1 倍消耗，持续到 2026 年 9 月底。想省额度就挑非高峰期用。
进阶路线，自己填 API Key 接第三方模型
ZCode 的一大优势是不锁死在一家模型上。你可以接 Claude、DeepSeek、Moonshot、OpenRouter，甚至自己部署的模型。因为我目前还没抢到GLM5.2的套餐，所以我暂时接入deepseek的大模型来演示。
操作路径，点聊天框里的「Manage Models」→ 进入模型设置页面。
接 Anthropic（Claude）
左侧选 Anthropic → 打开开关 → 填入信息
Endpoint: https://api.anthropic.comAPI Key: sk-ant-xxxxx（你自己的 key）可用模型: claude-sonnet-4-5, claude-opus-4-6 等接 DeepSeek
点「Add Provider」→ 填入信息
Provider 名字: DeepSeekAnthropic 协议 Endpoint: https://api.deepseek.com/anthropicAPI Key: 你自己的 DeepSeek API Key模型: deepseek-v4-pro, deepseek-v4-flash
点击添加供应商之后显示模型已启用：
到你的zcode主页面去看下模型就看出来配置成功了：
接 Moonshot（Kimi）
Endpoint: https://api.moonshot.cn/anthropicAPI Key: 你自己的 Moonshot API Key模型: kimi-k2.6, kimi-k2.5配完保存，在聊天框右下角就能看到你添加的模型，随时可以切换。
Endpoint 避坑，这个一定要看
如果你买的是 GLM Coding Plan，填 Endpoint 的时候千万别填成普通 API 地址。
Coding Plan 专用的 OpenAI 兼容地址是
BigModel（国内）: https://open.bigmodel.cn/api/coding/paas/v4Z.ai（海外）: https://api.z.ai/api/coding/paas/v4如果你填成了普通的 API 地址（比如 https://open.bigmodel.cn/api/paas/v4），可能出现「能连上、能对话、但额度不走 Coding Plan」的情况。到时候你以为自己在用套餐，实际消耗的是账户余额或者直接报错。
怎么判断配对了 配完之后发一条消息测试，如果能正常回复并且在用量统计页面看到 Coding Plan 额度在扣，就对了。
5 第一个任务，让 ZCode 从零创建一个小工具
模型配好了，接下来真正干活。
操作步骤
在电脑上新建一个空文件夹，比如叫 my-first-project在 ZCode 里打开这个文件夹（文件 → 打开文件夹） 在输入框里输入下面这段 Prompt，直接复制
帮我做一个本地用的记账小工具。单个 HTML 文件就行，不用后端。功能：输入金额和备注，点「记一笔」就添加到下面的列表里。列表每行显示时间、金额、备注，底部显示总计。数据存在 localStorage 里，刷新不丢。有一个「导出 CSV」按钮，点了直接下载。样式不用花哨，能用就行。
4. 点发送
你会看到什么
发出去之后，ZCode 会弹出权限确认框，问你是否允许它创建文件、执行命令。这是正常的安全机制，看一眼它要做什么，确认就行。
确认后 ZCode Agent 开始干活。你能看到它的执行过程，读取了什么、创建了哪些文件、写了什么代码。文件变更面板会显示新增的文件列表。
怎么判断成功
Agent 做完后会给一个总结。你用浏览器打开它创建的 HTML 文件，试着记几笔账，刷新页面看数据还在不在，点导出 CSV 看能不能下载，都没问题就算成功了。
没成功怎么办
如果 Agent 中途报错了，别急着重开任务。把错误信息复制过来，直接在当前对话里跟它说「刚才报错了，错误信息是 xxx，请修复」。ZCode 的优势就是能保持上下文，在同一个任务里继续修。
如果创建出来的页面打不开或者样式不对，直接描述问题让它改，比如「按钮没有居中，请修复 CSS」。
6 第二个任务，让 ZCode 读懂一个真实项目
这个场景面向开发者。你接手了一个老项目，几十个文件夹，代码看不过来。先让 ZCode 帮你梳理。
在 ZCode 里打开你的项目目录 输入这段 Prompt
你先不要修改任何文件。我刚接手这个项目，完全不了解。请帮我搞清楚几件事：这个项目是干什么的？用了什么技术栈？我本地要跑起来的话，需要装什么、配什么、执行哪几条命令？核心业务逻辑在哪几个文件里？有没有 .env 或者配置文件需要我手动填的？如果有坑（比如特定的 Node 版本、需要本地数据库之类的），提前告诉我。最后帮我整理一份「新人接手速查表」，我存下来以后查。
开头那句「你先不要修改任何文件」很重要。 不加这句的话，ZCode 可能一边分析一边就开始「顺手」改代码了。你只想让它读，不想让它动手，就必须明确说。
在做完上面两个任务后，我第一次感觉到zcode作为国产agent的能力确实已经很不错了。我用的deepseek-v4-pro模型体验的，如果用GLM-5.2模型估计体验更好。
项目太大怎么办
如果项目文件特别多，ZCode 可能分析不完整。这时候缩小范围，指定让它看某个目录。比如「请只看 src/modules/user 目录，帮我梳理用户管理模块的结构」。
7 第三个任务，让 ZCode 修一个真实 Bug
不要只说「帮我修 bug」。你要告诉它哪个地方出了问题、报了什么错。
操作步骤
先复制你的错误日志或报错截图 在 ZCode 里输入
用户反馈下单之后页面一直转圈，后台日志报了这个错：（把你的报错日志粘贴在这里）先不要改代码。帮我做三件事：1. 定位是哪个文件、哪段逻辑抛出的异常2. 分析可能的原因，列出你的推理过程3. 给我一个修复方案，我看完觉得靠谱了再让你动手看它的分析结果，确认方案合理后再让它改
为什么不要让它一上来就直接改？ 因为 Bug 修复不是越快越好，是越准越好。让它先分析、先定位、先给方案，你看了觉得对路再让它动手。这样即使它分析偏了，你也没有损失。直接改的话，它可能改错地方，你还得花时间回滚。
改完之后怎么验证
看 diff。ZCode 会显示它改了哪些文件、每个文件改了什么。红色是删掉的内容，绿色是新加的内容 
如果项目有测试，让它跑一遍测试 启动项目验证修复效果 确认没问题了再提交
8 怎么看 ZCode 改了哪些文件
这一节很重要。不管 ZCode 做了什么任务，你都要养成看 diff 的习惯。
ZCode 界面里有一个文件变更面板，会列出当前任务中所有被修改、新增、删除的文件。点进去能看到具体的变更内容。
红色背景 / 带减号的行 = 被删掉或替换的旧内容
绿色背景 / 带加号的行 = 新加的内容
这个是我让zcode帮我优化了刚刚那个小工具美观的问题：
什么时候一定要仔细看 diff
改了你不认识的文件的时候。改了配置文件（.env、config、数据库配置）的时候。删除任何文件的时候。涉及权限、安全、密码相关代码的时候。
如果发现改动不对，拒绝这次变更就行，ZCode 不会强制覆盖。你可以告诉它「这个改法不对，原因是 xxx，请换个方案」。
9 四种权限模式怎么选
ZCode 有四种权限模式（在 3.x 版本中），控制 Agent 干活时需要多少人工确认。
变更前确认
每次改文件、每次跑命令都会先问你。适合改关键代码、生产配置、数据库相关文件的时候。
小白推荐程度，第一次用 ZCode 建议先用这个，每步都看清楚它在做什么。
自动编辑
文件修改自动通过，但执行命令还是会问你。适合改样式、写文档、批量重构这种文件密集型任务。
规划模式
Agent 先分析需求、输出一个执行计划，你确认后它才开始动手。适合复杂任务、大重构、你不确定该怎么做的时候。先对齐思路再执行。
完全访问
所有操作直接执行，最少打断。只在你完全信任当前环境、任务很明确的时候用。涉及数据库操作、Git push、删除文件这种事，不要用这个模式。
10 Goal Mode，让它持续干到完成
这是 ZCode 里我觉得最值得单独拿出来讲的功能。
很多 Agent 工具做复杂任务的时候，你经常需要手动推进，做完一步确认一下再继续。Goal Mode 的思路不一样，你设定一个明确的、可验证的目标，ZCode Agent 会自己一轮一轮迭代，每轮结束自动检查目标是否达成，没达成就自动继续，直到目标完成才停下来。
怎么用
在输入框里打 /goal 加上你的目标。
/goal 我现在有一个任务是我日常做自媒体需要做的，就是我需要把我的公众号已发表的文章转发到X文章里面去，那我如果单独去复制文字的话， 拷贝到X文章里面去，字数多的话就会乱码，并且图片不显示，所以我想让你能不能做一个工具，我给你一个公众号文章链接，你帮我把文章提取出来，并且结构和图片都在里面，我直接可以复制到X文章里面，结构不乱，图片和视频都在的那种工具，你明白我的意思吗？
最后真的从公众号链接复制出文章来了。
什么叫「好目标」
好目标 = Agent 每轮可以自己验证是否完成。
「优化一下代码」不是好目标，太模糊，Agent 不知道什么时候算「优化完了」。
「让 npm run build 通过」是好目标，Agent 每轮结束跑一遍 build 就知道过没过。
「把 Lighthouse 性能评分提升到 90 以上」是好目标，跑一遍 Lighthouse 就能验证。
管理命令
/goal replace <新目标> 替换当前目标，不用重开任务/goal pause 暂停/goal resume 恢复/goal clear 清除目标设好目标后，右上角会出现一个目标卡片，显示当前状态、已经跑了多长时间、消耗了多少 token、迭代了几轮。
跑长目标的时候，建议把权限模式调成 Auto Edit 或 Full Access，减少中途打断。
中途失败怎么办
如果 Agent 连续几轮都没有进展或者在兜圈子，用 /goal pause 暂停。看一下它卡在什么地方，给它一些额外的提示或约束，然后 /goal resume 恢复。
11 AGENTS.md，让 ZCode 记住你的项目规则
如果你每次开新任务都要跟 ZCode 说一遍「这是 Spring Boot 项目」「不要改数据库表结构」「提交前必须跑测试」，那就太累了。
AGENTS.md 就是解决这个问题的。你把项目规则写在一个文件里，ZCode 启动任务时会自动读取。
放在哪里
ZCode 读取两个位置
~/.zcode/AGENTS.md 全局规则，对所有项目生效。适合写你的个人偏好和通用规范。
项目根目录/AGENTS.md 项目规则，只对当前项目生效。适合写项目特有的约束。
两个都存在的话，ZCode 会把全局规则和项目规则合并在一起给 Agent 用。
一个真实的项目 AGENTS.md 模板
在你的项目根目录新建一个文件，文件名就叫 AGENTS.md，内容参考
# 项目规则这是一个 Spring Boot + MyBatis 项目。要求：1. 不要随意修改数据库表结构2. 不要新增第三方依赖，除非我明确同意3. 修改核心业务前，先说明影响范围4. 新增接口必须有参数校验5. 提交前必须运行 mvn test6. 不要把 API Key、Token、密码写进代码7. 不要直接执行 git push，除非我明确要求前端项目也可以写一个
# 项目规则这是一个 Next.js + TypeScript 项目。要求：1. 使用现有组件库，不新增 UI 依赖2. 样式用 Tailwind CSS，不写内联样式3. 修改前先跑 npm run build 确认当前状态4. 改完后跑 npm run lint 和 npm run test5. 不要动 next.config.js 除非我明确要求保存后，下次在这个项目里新建任务，ZCode 就会自动读取这些规则。
注意 如果你之前用 Claude Code，项目里可能有 CLAUDE.md。ZCode 不会持续读取 CLAUDE.md，它只在第一次当作迁移参考。以后的规则统一写在 AGENTS.md 里。
12 Command / Skill / MCP / Plugin / Subagent 是什么
ZCode 有一堆进阶概念，名字都不一样，小白容易搞混。用大白话解释一遍。
Command = 常用提示词的快捷方式
你每次提交前都要让 ZCode Review 代码，每次都复制一大段 Prompt 太累。把这段 Prompt 存成 Command，以后输入框里打 /review 就能一键触发。
ZCode 自带两个 Command。/goal 管理长任务目标，前面讲过了。/compact 压缩当前对话上下文，对话太长的时候用。
自定义 Command 在设置里的 Commands 页面创建，文件存在 ~/.zcode/commands 目录下。如果你之前在 Claude Code 里有自定义 Command，ZCode 支持一键导入。
Skill = 一套可复用的工作流
比 Command 更重一级。Command 只是一段 Prompt，Skill 可以包含脚本、模板、示例文件。适合复杂的工作流，比如「发版前生成 changelog + 检查测试 + 生成发布说明」。
MCP = 给 Agent 接外部工具
让 ZCode 能读网页、搜索、连数据库、看截图。通过配置 MCP 服务器实现，在设置里统一管理。
Plugin = 把多个能力打包
可以把 Skill、Command、Subagent 和 MCP 服务器打包成一个插件，团队内一键分发。
Subagent = 分工干活的小 Agent
目前 ZCode 有一个内置 Subagent 叫 Explore，专门做代码搜索和分析，只读不改。主 Agent 遇到需要大范围搜索代码的时候会自动启动它，你不需要手动操作。
这些功能都偏进阶，刚上手不用管。先把前面的基础流程跑通，后面需要了再来看这部分。
13 Remote Control 和 Bot Channel
你在电脑上给 ZCode 下了一个大任务，用 Goal Mode 跑，可能要半小时。你想出去吃个饭，手机上也能看进度。
Remote Control 手机遥控
电脑上打开 ZCode 左下角侧边栏点「Remote Connection」 
会弹出一个二维码和链接 
手机扫码或打开链接 手机上就能看到当前工作区了 
手机上可以做的事，查看 Agent 状态和最新输出、发送补充指令、确认或停止任务。这个真的好，国产agent也做的这么溜了啊，虽然这是网页端的，但是跟之前我们之前写过的codex app那个ChatGPT远程连接功能也差不多，都是可以手机下达指令给桌断面。
要搞清楚的限制 手机端只是一个远程控制器，代码修改和命令执行仍然在电脑上的 ZCode 里完成。手机不是在本地跑代码。
Bot Channel 飞书/微信 Bot
ZCode 支持通过飞书和微信 Bot 来触发和推进任务，在群里 @ bot 就行。适合团队协作场景。其他平台以官方后续更新为准。
用手机微信下达指令也能同步到zcode桌面端。 国内agent这波学习能力还是可以的啊。
14 常见失败场景和解决办法
这一节是零基础教程里最重要的部分。
登录后没有模型可以选
可能原因，没有订阅 Coding Plan、没有配置 API Key、选错了通道（国内用户选了海外通道或反过来）。
处理，去模型设置页面检查 Provider 是否开启、API Key 是否填对、Endpoint 是否正确。
API Key 填了还是不能用
可能原因，Endpoint 填错了（最常见）、协议选错了（Anthropic 和 OpenAI 协议不能混）、API Key 过期或余额不足、模型名填错。
处理，对照本文第 4 节的 Endpoint 重新填写。如果你用的是 Coding Plan，一定要用 Coding Plan 专用 Endpoint。
终端里配过 GLM API，ZCode 里还是没有
这是正常的。ZCode 和 Claude Code 是独立的系统，配置不会同步。你需要在 ZCode 里重新配一次。
ZCode 说改完了，但项目跑不起来
最常见的情况。不要慌，把报错信息复制过来，在当前对话里跟它说「报了这个错，请修复」。保持在同一个任务里继续修，不要重开新任务，否则上下文就丢了。
它一直乱改文件
处理，切回 Plan Mode 或 Confirm Before Changes 模式。在 Prompt 里加上「先不要修改文件」「先给方案我确认后再改」。
执行命令卡住了
处理，停止当前任务（点停止按钮），把终端输出复制出来，新建一条消息让它分析为什么卡住。
项目太大，分析不准确
处理，缩小范围。用 @ 指定具体文件，或者指定「只看 src/modules/user 目录」。不要指望它一次性理解一个几万个文件的大型项目。
害怕它删文件
处理，用 Confirm Before Changes 模式，每次操作都确认。看 diff，看它要删什么，不对就拒绝。另外你的项目本身应该有 Git 版本管理，真改错了可以回滚。
@ 选不了文件夹
这是 ZCode 的设计。输入框里 @ 只能选文件，不能选文件夹。要给 Agent 整个文件夹做上下文，直接把文件夹从文件管理器拖进输入框。
15 ZCode 适合谁，不适合谁
适合的人
想做简单小工具但不会写代码的人。ZCode 的门槛比命令行工具低很多。
接手老项目需要快速上手的开发者。让 ZCode 先梳理一遍结构，比自己翻文件快。
想试试国产模型在编程场景下到底能做到什么程度的人。GLM-5.2 的性价比确实值得一试。
一句话判断标准 如果你现在用 Cursor 或 Claude Code 已经很顺了，没有账号和网络的痛点，那 ZCode 对你来说就是多一个选择，不是必须迁移。如果你一直想试 Agent 编程但被门槛挡住了，ZCode 是目前国内上手最快的入口。
好了，以上觉得有用，点赞、在看、转发三连，让更多使用 codex app 的朋友去使用。谢谢你看我的文章，我们，下次再见。
