智谱 ZCode 上手实录:我决定卸载Claude和Codex

第一次打开 ZCode，我的感觉不是「另一个Coding Agent」，而是这玩意把整套开发流程塞进了一个桌面应用：需求理解、计划拆解、代码修改、验证收口，全都在同一个上下文里推进。它不是 IDE 插件，也不是命令行工具，而是智谱围绕 GLM-5.2 深度调优的 Agentic Development Environment（ADE）。

对我来说，ZCode 还有一个很现实的吸引力：它是国产方案。前几天的Claude Code植入后门的行为太恶劣，是时候要国产替换了。ZCode 给了国内开发者一条可控的退路：主链路自研、底座在国内、付费和合规都按国内平台走。这不是说国外工具一定不能用，而是多一个国产替代选项，对很多团队来说意义重大。

我会按实际使用顺序写：

• • 安装与模型接入
• • ZCode Agent 怎么交互
• • Goal 目标模式
• • 远程和 Bot、Skill 与 Command、MCP 扩展
• • 子智能体
• • 安全确认
• • 任务管理
• • 我自己的使用建议。

一、ZCode 到底是什么，适合谁

官方 slogan 是「简单、迅捷、氛围十足」。抛开营销味，它真正想解决的是一个很真实的问题：用 AI 写代码时，任务一复杂就容易「断片」。你让 Agent 修个 Bug，它改两行，下一轮就忘了 Git 状态；或者长任务需要你不停地打「继续」。

ZCode 的解法大概有三点：

• • 借助 GLM-5.2 的 1M 长上下文，把目标、文件、终端输出、浏览器上下文、执行模式、Git 状态全塞在一个任务里。
• • 自研的 ZCode Agent 对长程任务（Long Horizon Task）做了专门优化，能连续地规划、执行、验证。
• • 桌面端、手机 Remote、微信/飞书 Bot 都能跟进同一个工作区任务。

适合干什么？重构一个模块并保持测试通过、修掉一堆 TypeScript 编译错误、把页面 Lighthouse 分数提到 90 以上、整理遗留代码并补文档。说白了，就是一句话能说清目标，但需要多轮才能干完的事。

二、安装与首次启动

ZCode 是桌面应用，支持 macOS（Apple Silicon / Intel）、Windows（x64 / ARM64）和 Linux（Beta）。截至我写这篇，最新版是 v3.2.2。

下载直接上官网：https://zcode.z.ai/cn

安装没太多花样：

• • macOS：打开.dmg，把 ZCode.app 拖进 Applications。
• • Windows：跑安装向导。
• • Linux：加内测群拿安装包，给执行权限后直接跑。

首次启动会进设置向导，完成后点左下角「连接使用」登录。之前用过 Claude Code 或旧版 ZCode 的话，可以选择数据迁移向导导入对话记录，不想折腾也能先跳过。

登录后选一个项目目录当工作区，然后输句简单指令——比如「列出当前目录的文件」——确认 Agent 能正常回话就行。

几个常见坑：

• • macOS 提示「已损坏，无法打开」：在终端执行xattr -dr com.apple.quarantine /Applications/ZCode.app。
• • Windows 被防火墙或杀软拦截：先关实时防护，或把安装目录加白名单。
• • Linux 跑不起来：确认加了可执行权限，有些发行版还要额外装fuse。

三、连接模型

ZCode 配置模型有两个入口：首次启动的欢迎页，或者进应用后点对话框里的模型名称 → 管理模型。

国内用户推荐GLM Coding Plan（BigModel），海外用户推荐Z.ai Coding Plan。这两种都是账号授权登录，不用手动填 API 端点。

新用户首次连 BigModel 或 Z.ai，有 5 天免费体验额度：

• • GLM-5.2：300 万 Token / 天
• • GLM-5-turbo：200 万 Token / 天
• • 合计每天 500 万 Token

订阅 GLM Coding Plan 后，ZCode 会直接扣套餐额度。到 2026 年 7 月 31 日之前还有个额度折算活动：非高峰期按 0.67 系数扣减，相当于同样额度多用约 1.5 倍。

Coding Plan 分三档（美元计价）：

• • Lite：约18），适合轻量迭代和小仓库。
• • Pro：约72），5 倍 Lite 额度，带精选 MCP 工具。
• • Max：约160），20 倍 Lite 额度，适合高频和中大型仓库。

如果你已经有其他平台的 API Key，也能手动接入：

• • Moonshot
• • MiniMax
• • MiMo
• • Deepseek
• • 阿里百炼Token Plan
• • 火山方舟Coding Plan
• • 任意兼容 Anthropic / OpenAI 协议的自定义供应商

以 DeepSeek 为例：名称填 DeepSeek，Anthropic 接口地址填https://api.deepseek.com/anthropic，OpenAI 接口地址填https://api.deepseek.com/v1，再填 API Key 即可。

四、ZCode Agent：默认入口

ZCode Agent 是主 Agent，也是新建任务最直接的入口。它深度适配 GLM-5.2，能理解工作区、任务列表、文件引用、执行模式和 Git 分支状态。

输入框里有一组快捷符号，用来补上下文：

• •@：引用工作区里的文件。
• •#：关联历史对话。
• •/：调用已保存的命令。
• •$：调用技能。
• •+：上传附件。

组合起来比纯打字高效得多。比如：@src/utils.ts 把这个函数的异常处理改得更具体。

项目指令文件

想让 Agent 长期遵守项目约定，可以写AGENTS.md。ZCode 会读两个位置：

• • 用户全局指令：~/.zcode/AGENTS.md
• • 当前工作区指令：<workspace>/AGENTS.md

两个都存在时，会先拼全局指令，再拼工作区指令。适合写技术栈、目录结构、代码风格、提交前验证命令、高风险文件注意事项。

注意：ZCode 不会把CLAUDE.md 当成持续指令来读，只会在 onboarding 时一次性迁移到AGENTS.md，后面以AGENTS.md 为准。

执行模式

执行模式决定 Agent 改文件、跑命令前要不要确认。输入框聚焦时按Shift + Tab 可快速切换：

• • 变更前确认：每次改文件前都问。适合关键代码、生产配置。
• • 自动编辑：自动改文件，但命令仍要确认。适合常规迭代。
• • 计划模式：先给计划，确认后再动手。适合复杂任务。
• • 完全访问：尽量少确认。适合目标明确、风险低的小任务。

我的习惯：不熟的用计划模式；熟了切自动编辑；碰生产配置或高危文件就开变更前确认。

推理强度

输入框右下角有个思考图标，可以开关深度思考：

• • Off：直接回答，最快。
• • On：默认最深思考深度，适合复杂架构设计、疑难 Bug 排查。

五、目标模式（Goal）：让 Agent 自己跑到完

这是 ZCode 和很多 AI 编程工具不太一样的地方。面对多轮才能完成的任务，可以在输入框里设目标：

/goal <目标描述>/goal replace <新目标>/goal pause/goal resume/goal clear

比如：/goal 修复所有 TypeScript 编译错误，并让 pnpm test 全部通过。

设定后，Agent 每轮迭代结束会自动校验目标是否完成。没完成就继续跑，完成了才收尾。右上角摘要面板会显示目标状态、累计时间、累计 Token 和迭代轮次。

Goal 适合搭配「完全访问」或「自动编辑」模式，减少中途被打断。你不用一直盯着喊「继续」，设好目标后去泡杯咖啡也行。

六、Remote Control 与 Bot Channel：多端跟进

Agent 长任务跑起来后，难免要离开电脑。ZCode 给了两种远程跟进方式。

Remote Control

临时扫码接入。点 ZCode 左下角的手机图标，打开「移动端远程控制」，会生成二维码和连接地址。手机扫码或浏览器打开后，就能看当前任务、输新指令、追问或中止。

注意：同一时间只支持一个手机页面连接，而且只能访问当前打开的工作区。

Bot Channel

把入口放进常用聊天工具。目前支持微信和飞书，后面会补钉钉、Discord、企业微信。

• • 微信：桌面选微信 → 手机扫码确认 → 直接在微信里和 Bot 对话。
• • 飞书：先在手机上创建智能体应用，然后发送绑定命令（如/bind C67356）完成绑定。

绑定后，你可以在微信或飞书里看进度、发指令。Bot Channel 比 Remote 更适合长期回访同一个工作区。

七、Skill 与 Command：把重复操作固化下来

Skill 和 Command 都是沉淀复用能力，但粒度不同。

• • Command：存一段常用提示词，用/command-name 调用。
• • Skill：一套完整工作说明，含触发场景、处理步骤、输出要求，用$skill-name 调用。

如果你只是想说「每次帮我生成提交说明」，Command 就够了；如果要「先读代码、再按检查清单 review、最后输出报告」，那就做成 Skill。

创建 Skill

Skill 是一个目录加一份SKILL.md，默认放这里：

~/.zcode/skills/<skill-name>/SKILL.md

最小示例：

---name: code-review-checklistdescription: Review code changes with a focused checklist for correctness, regressions, tests, and maintainability.---# Code Review ChecklistUse this skill when reviewing a pull request, merge request, or local diff. Focus on correctness, regressions, missing tests, risky API changes, and maintainability.

创建后在「设置 → 技能」里刷新并启用，聊天中输$code-review-checklist 就能调用。

如果你已经在 Claude Code、Codex CLI、OpenClaw、Augment、Windsurf 里维护过技能，可以直接导入 ZCode，支持软链或复制两种方式。

创建 Command

在「设置 → 命令」里新建，字段包括作用域（用户/工作区）、名称、描述、参数提示和提示词。保存后是.md 文件，放在~/.zcode/commands 或项目目录下。

ZCode Agent 目前内置两个命令：

• •/goal：管理目标模式。
• •/compact：压缩当前对话上下文，保留关键信息。

八、MCP 服务器：扩展 Agent 的工具箱

MCP（Model Context Protocol）能把文件系统、浏览器、记忆、数据库等外部能力接到 Agent 里。ZCode 统一管理 ZCode Agent 使用的 MCP 服务器。

在「设置 → MCP 服务器」里可以新建、启用、停用或删除 MCP。支持三种类型：

• • stdio：本地命令，例如npx -y @modelcontextprotocol/server-memory。
• • HTTP / SSE：远程服务。
• • 完整配置：直接粘贴 JSON。

配置文件路径：

• • 用户级：~/.zcode/cli/config.json，键为mcp.servers。
• • 工作区级：<项目根>/.zcode/config.json，键为mcp.servers。
• •.agents 兼容：~/.agents/mcp.json 或<项目根>/.agents/mcp.json，结构为mcpServers。

读取优先级：工作区优先；同一作用域内.zcode 强优先于.agents；设置面板新增/编辑始终写回.zcode。

智谱官方推荐了几个 MCP：

• •zai-mcp-server：视觉理解，分析图片、截图。
• •web-search-prime：联网搜索。
• •web-reader：网页读取与解析。

如果你已经在 Claude Code、Codex CLI、OpenCode 里配过 MCP，可以直接导入。ZCode 会扫描~/.claude/settings.json、~/.codex/config.toml、~/.config/opencode/opencode.json 和~/.agents/mcp.json。

九、子智能体：把任务拆出去并行做

ZCode 内置两个子智能体：

• • general-purpose：通用型，完整工具权限，适合独立实现小功能、并行整理文件。
• • Explore：只读搜索和代码库调研专家，适合大范围检索、调用链梳理、风险点收集。

主 Agent 判断任务需要独立上下文或并行调研时，会自动启动子智能体。子智能体干完后把结果汇总回主对话。

你也可以在「设置 → 子智能体」里创建自定义子智能体（Beta），比如「代码审查员」「测试编写者」「文档调研员」。配置字段包括名称、颜色、模型、描述、可用工具和系统提示词。保存后写入~/.zcode/agents/<name>.md。

目前自定义子智能体只支持用户级，不支持项目级；子智能体在前台并行执行，后台执行还没开放。

十、安全操作确认：先看清楚再允许

ZCode 的权限控制放在任务界面里。Agent 发起需要授权的操作时，任务会暂停，界面展示它计划执行的命令、文件改动或工具调用，确认后才继续。

执行模式前面已经说过。除此之外，每个确认弹窗还有几个选项：

• • 允许：只授权当前这一次。
• • 始终允许：当前及后续同类型操作都允许。
• • 拒绝：禁止当前操作。
• • 始终拒绝：禁止当前及后续同类型操作。

有些场景下还有「允许本会话」「始终允许本项目」等更细粒度选项。

我的建议：

• • 不确定时先点「允许」，别直接「始终允许」。
• • 大改动用计划模式。
• • 涉及生产配置、系统级命令时开「变更前确认」。

十一、任务与文件管理

左侧边栏是任务管理中枢。任务视图有三种组织方式：

• • 分组：自定义分组，按主题或优先级整理。
• • 工作区：按项目平铺任务。
• • 时间线：按时间倒序，找最近做的事最快。

分组可以选 7 种颜色，任务可以拖拽排序。已完成的任务可按保留期自动归档（3 / 7 / 14 / 30 天）。

文件树入口在工作区卡片右侧。进去后可以：

• • 搜索文件。
• • 一键只看 Git 变更文件。
• • 单击在右侧预览，双击用默认编辑器打开。
• • 拖拽到对话框或右键「添加到聊天」，把文件引用进对话。

顶部还有「仓库 Wiki」入口，会基于当前仓库自动生成结构化文档。接手新项目时，先点进去看一眼，能很快建立全貌。

十二、我的使用建议

1. 1.先写 AGENTS.md。把技术栈、命名规范、提交前验证、高危文件写进去。Agent 不是读心术，项目指令能显著降低它胡说八道的概率。
2. 2.复杂任务用 Goal。一句话目标 + 可校验条件，比连续多轮对话稳得多。
3. 3.善用符号。@ 引文件、$ 调技能、/ 调命令，比纯自然语言省上下文。
4. 4.高危操作开确认。默认模式或变更前确认，尤其是你不熟悉的项目。
5. 5.导入外部资产。从 Claude Code/Codex/OpenCode 迁移的话，技能、命令、MCP 都能一键导入，省掉重复配置。
6. 6.手机端当辅助，别当主力。Remote 和 Bot 适合跟进长任务、追加指令，真正复杂的代码修改还是桌面端舒服。

十三、总结

ZCode 不是又一个AI编码工具。它想做的事是把 GLM-5.2 的长上下文和长程任务能力，真正落进桌面端的开发工作流。上下文保持稳、长任务能自己跑到目标、多端可以跟进、技能和 MCP 扩展灵活，这些是它的长处。

代价也明显：你得花点时间配置 AGENTS.md、技能、MCP 和模型接入。如果你只是偶尔让 AI 写几行代码，可能有点大材小用；但如果你经常处理「一句话目标、多轮才能完成」的复杂任务，ZCode 值得认真试试。

官网：https://zcode.z.ai/cn文档：https://zcode.z.ai/cn/docs