信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。
1. 定位
【有据可查】ZCode 是智谱 Z.ai 推出的桌面 ADE（Agentic Development Environment），官网自称 "Official Harness for GLM-5.3"，内置自研 ZCode Agent，并围绕 GLM-5.3 深度调优；内置 GLM-5.3-Flash 处理截图理解等多模态任务。支持远程工作区、Bot Channel、手机远程控制。来源：ZCode 官网、ZCode Docs、Z.ai 开发者文档
2. 订阅方案结构（价格以官网为准）
【有据可查】ZCode 本身可免费下载；模型用量主要来自 GLM Coding Plan（官网展示 Lite / Pro / Max 三档，按"周额度/Credits"计，Pro 约为 Lite 6 倍、Max 约 14 倍用量），也可以用开放平台 API Key 按量付费。官网注明"价格与权益可能变化，以 z.ai 为准"。来源：ZCode 官网
| 档位 | 定位（官网描述） | 层级 |
|---|---|---|
| Lite | 小仓库轻量迭代 | 有据可查 |
| Pro | 中型仓库日常开发，含精选 MCP 工具、更快生成 | 有据可查 |
| Max | 中大型仓库进阶用户，高峰期专属资源 | 有据可查 |
【有据可查】GLM Coding Plan 官方称兼容 20+ 款 Agent 工具（含 Claude Code 等）。
国际站（z.ai）与国内站（BigModel / bigmodel.cn）是两套入口，套餐、价格、计费币种可能不同。【待考察：两站具体差异】
3. 安装【有据可查】
来源：Install
| 平台 | 安装包 |
|---|---|
| macOS | .dmg（Apple Silicon / Intel） |
| Windows | .exe（x64 / ARM64） |
| Linux | .AppImage / .deb / .rpm（x64、ARM64） |
# Linux AppImage
chmod +x ZCode-*.AppImage && ./ZCode-*.AppImage
- 首次启动有引导页；可用"数据迁移向导"导入 Claude Code 与旧版 ZCode Agent 的历史对话（其它工具暂不支持）。
- 代理设置：Settings → General 可配置代理与自定义根证书，保存后重启生效；生效后模型请求、MCP、Agent 执行的命令行工具和界面请求都会走该代理。（这是企业网络/内网代理的常规配置项，请合规使用。）
4. 首次配置：连接模型【有据可查】
左下角 Connect → 三种方式：
- Connect Z.ai：登录 Z.ai 账号；若账号有 GLM Coding Plan，直接使用套餐额度。
- Connect BigModel：国内开放平台账号。
- Use API Key：手动填 Key。
⚠️ 最容易踩的坑：用 Coding Plan 的 API Key 时，Base URL 必须是编程专用端点：
| 用途 | OpenAI 兼容 Base URL | Anthropic 兼容 Base URL |
|---|---|---|
| GLM Coding Plan | https://api.z.ai/api/coding/paas/v4 |
https://api.z.ai/api/anthropic |
| 普通 API（按量） | https://api.z.ai/api/paas/v4 |
— |
来源：Z.ai 开发者文档 · ZCode、Connect Models
📝 更正提示：DSH 添加模型：协议、地址、密钥与模型 ID的对应表只列了国内站
https://open.bigmodel.cn/api/paas/v4。国际站与 Coding Plan 的端点不同，请以本表和官方文档为准。
5. 权限 / 安全模型【有据可查】
| 模式 | 行为 | 适合 |
|---|---|---|
| Ask before changes（默认） | 每次编辑文件或执行命令前确认 | 关键代码、生产配置 |
| Edit automatically | 自动改文件，命令仍需确认 | 日常迭代 |
| Plan | 先计划，确认后再实施 | 重构、迁移、长任务 |
| Full access | 更少确认 | 可信环境 |
- 快捷键
Shift+Tab切换；弹窗选项 Allow / Always Allow / Reject / Always Reject。 - 弹窗出现时任务暂停、输入框被锁，防止误排队下一步。
- 高权限模式下工具栏持续显示风险状态。
实践提醒【待考察/推测】："Always Allow" 很省事，但等于给同类操作开了长期绿灯。对 rm、git push、部署类命令，建议只点"Allow"。
6. 常用功能与工作流
| 功能 | 说明 | 层级 |
|---|---|---|
/goal 目标模式 |
设定目标后自动多轮推进，每轮结束独立校验是否完成；可配置用量预算；与 Plan 模式冲突 | 有据可查：Goal Mode |
| 旁路对话 | 主任务等待权限时，可通过 + 菜单开新对话问别的问题（不继承主任务目标） |
有据可查：ZCode Agent |
| 项目说明 | 建议写清技术栈、目录结构、校验命令、高风险文件、协作偏好 | 有据可查 |
| Review 面板 / 提交流程 | 变更审查与提交 | 有据可查 |
推荐工作流（实践建议）【社区共识/待考察】：
7. 接入自定义模型【有据可查】
Model Settings → Add Provider → 命名 → 选择或填写 Base URL（支持 Anthropic / OpenAI 协议）→ 填 API Key → Add Model 填模型 ID → 打开启用开关。来源：Connect Models
8. 常见报错
| 现象 | 可能原因 | 处理 | 层级 |
|---|---|---|---|
| Coding Plan Key 报额度/权限错误 | 用了普通端点 /api/paas/v4 |
改为 /api/coding/paas/v4 |
有据可查 |
| 模型列表为空 | 账号权限/服务端返回列表为空 | 手动添加模型 ID | 有据可查 |
/goal 设置失败 |
在 Plan 模式下或任务运行中 | 切换模式/等本轮结束 | 有据可查 |
| 改了代理不生效 | 未重启 | 保存后重启应用 | 有据可查 |
9. 适合人群
- ✅ 喜欢桌面可视化、希望每一步都"看得见"的开发者
- ✅ 已购 GLM Coding Plan、想"一份套餐多个工具用"的人
- ⚠️ 看不懂命令的纯新手：弹窗依赖判断力（见AI 编程 Agent 怎么选：工具、权限与工作方式观点）
10. 本篇无法核实/需谨慎的点
- 国际站与国内站套餐差异、国内站 Coding Plan 端点。
- GLM-5.3 之外模型在 ZCode Agent 中的适配程度。
- "20+ 款工具兼容"的具体列表。
小白练习：把本文流程逐项走通
练习目标：接入正确的计费端点，完成一个可验收的小任务。
上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。
-
下载与系统和处理器匹配的安装包。安装并登录后，先打开一个只含练习文件的项目目录。
-
确认所用账户来自国际站还是国内站；再确认凭据属于 Coding Plan 还是普通 API。
-
打开连接模型入口，按原文分别填写连接方式、Base URL、Key 和模型 ID；保存后单独测试连接。
-
在执行模式中选择保守起点，先让它提出计划。每次权限弹窗都检查操作对象和具体命令。
-
需要目标模式时先写明完成标准，例如指定测试通过、只改某两个文件；再设置可用预算。
-
任务结束后进入 Review 查看文件改动，打开最终文件并测试。Always Allow 是持续授权，不等同于仅批准这一次。