天工开物KAIWU AI
工具指南 › ZCode › ZCode 使用指南(完整全套)
核实于 2026-11-08
工具指南·其十九核实于 2026-11-08

ZCode 使用指南(完整全套)

适用对象
想快速了解工具定位、核心功能和上手路径的中文用户
核对日期
2026-11-08
本页目录

本指南综合了 10 篇公众号实测与技术教程(2026-06-28 ~ 11-01)。文中的 [1]~[10] 对应文末「参考原文」,序号与 00_清单.md 一致。每张图下方注明出处与对应文章。素材之间说法不一致、计费模式变化或容易踩坑的地方,均用 ⚠️ 明确标出。

公众号素材涵盖了 2026 年中初发布到 10~11 月最新版本的深度实践(从 Codex 平替定位、闲时任务实操、办公与科研模式联动,到 24.7 亿 Token 极限压测)。指南补充了智谱 BigModel 开放平台技术标准、ZCode 权限模型与 BotChannel 规范,以 [官1]~[官6] 标注,查阅日期 2026-11-08。


一、定位:它是什么,适合谁

ZCode 是由智谱 AI(Zhipu AI)推出的全功能自主 AI 编程工作台与智能体系统,底层原生搭载智谱 GLM 系列基座大模型(如 GLM-5.2、GLM-4-Plus)[2][3]。

它最初在开发者圈内被称为**「国内最好用的 Codex 平替」,但随着版本迭代,ZCode 已经逐渐跳脱了单纯编码工具的藩篱,演化为一个集「全自主代码开发、Office 办公多模态处理、闲时夜间自主调度、科研文献综合挖掘」于一体的国产综合 AI 工作台** [2][6][7][10]。

图 1 全部下载页

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

1. 核心特性

  • 双模态工作空间:一键在「编程模式(Coding)」与「办公模式(Office)」之间无缝切换。白天帮你敲代码、改 Bug,晚上切到办公模式批量排版 PPT、清洗 Excel 报表 [6][7]。

  • 闲时任务(Off-Hours Task):支持将繁重的全库测试、跨模块重构、上万篇文献总结等长流程任务挂入闲时队列,关机/下班后让 AI 在后台自动熬夜推进 [5][8]。

  • 远程遥控(BotChannel):原生支持通过企业微信、飞书机器人或 Web 渠道远程向正在运行的 ZCode 下达指令并接收成果汇总 [3]。

  • 极度成熟的生态迁移:内置「Skills 迁移向导」,如果你此前在 Claude Code 或 Codex 中积累了大量自定义 Skill 与规则,ZCode 支持一键软链接无缝继承 [2]。

2. 和同类 AI 编码工具怎么比

维度智谱 ZCodeOpenAI CodexDeepSeek HarnessClaude Code
网络门槛国内网络直连,大厂企业级保障 [1][2]必须海外网络环境国内网络直连依赖海外网络环境
功能跨界能力编程 + Office 办公双模式 [6]仅专注代码与系统任务专注终端与代码 Harness专注端到端编码
异步长任务特有「闲时任务」机制,下班托管 [5]需长会话挂机支持 Auto 模式支持后台子代理
模型与算力原生深度优化 GLM-5.2,且支持外部 Key [3][4]深度绑定 OpenAI原生 DeepSeek,全开放深度绑定 Claude
多渠道远控内置 BotChannel,企微/飞书直连 [3]需自行搭建 MCP需自行搭建插件依赖官方云端联动

适合谁:

  • 受够了网络波动与封号风险的开发者:希望用上不输海外水准的自主 Agent,同时享受稳定极速国内直连网络的人 [2][10]。

  • 身兼数职的技术负责人与科研人员:不仅要写代码,还要读论文、做组会汇报、处理数据分析报告的科研党与复合型工程师 [7][8]。

  • 有大量挂机任务的工程团队:需要下班后让 Agent 自动跑全套回归测试、生成测试覆盖率报表的人 [5]。

不适合谁:

  • 追求极致精简、仅需要一个几兆大小轻量终端行级补全插件的人 [10]。

  • 仅需要无脑代码补全、完全不想让 AI 碰本地系统文件的人 [3]。


二、准备与安装

0. 先选路线:你属于哪种情况

你的情况推荐路线核心步骤
Windows / macOS 日常主力机使用全平台桌面客户端(推荐)看第 1、2 步 → 第三节快速上手
需要在无桌面的 Linux 服务器运行ZCode CLI 命令行版看第 2 步 CLI 说明
拥有智谱 BigModel 账号或编程套餐直接选择「智谱官方账号连接」看第 1 步「欢迎页三种连接」
想用 DeepSeek、本地 Ollama 驱动 ZCode选择「自定义供应商连接」看第四节「2. 接入第三方模型与 API Key」

1. 账号体系与三种连接方式

启动 ZCode 后,欢迎页提供了极其清晰的三种接入方式 [1]:

图 2 欢迎页三种连接

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

  1. 智谱账号登录 / 编程套餐(最省心):直接扫码绑定智谱账号。智谱推出了专属的「编程套餐」(按月定额包,支持无限量畅享特定规模的编码调用)[1]:

图 3 模型设置与编程套餐

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

  1. BigModel 开放平台 API Key 直连:填入你在智谱开放平台申请的 API 密钥,按实际 Token 产生账单 [1]:

图 4 BigModel-API配置

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

  1. 自定义模型供应商(Custom Provider):挂载第三方模型(如 DeepSeek、SiliconFlow、本地 Ollama)[3]。


2. 客户端安装与生态迁移

第一步:下载并安装

从智谱官网下载最新版安装包(支持 Windows 64位、macOS Apple Silicon/Intel、Linux AppImage)[1]。

第二步:运行「生态迁移向导」(可选)

如果你的电脑中此前已经安装过 Claude Code 或 Codex,ZCode 会在初始化时主动提示检测到了现有配置,并支持一键建立 Skills 与 Rules 软链接 [2]:

图 5 迁移向导Skills软链

图源:[2] 墨玩AI《如果你用不了Codex,那我推荐试试它的国产平替,智谱Zcode保姆教程来了》

这意味着你之前花心血调优的指令库与工作流,零成本瞬间搬入 ZCode [2]。


3. 权限模式与思考强度配置

(1)细粒度权限控制

在主界面右上方或设置中,ZCode 提供了完善的安全权限分级 [1][3]:

  • 普通模式(Ask Before Write):修改文件或执行 Shell 命令前,必须弹出批准卡片 [1]。

  • 自动编辑模式(Auto Edit):文件写入自动执行,但终端危险命令依然弹窗确认 [3]:

图 6 权限模式含自动编辑

图源:[3] AI一手《ZCode 零基础教程:国产 GLM-5.2 Coding Agent,从安装到真正干活(保姆级全攻略)》

  • 全自主模式(Autonomous Mode):全自动循环推进,适合挂机执行闲时任务 [1]:

图 7 权限模式含自主模式

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

(2)模型思考强度滑块

针对不同的任务复杂度,ZCode 支持动态调节思考强度(Thinking Depth)[1]:

图 8 模型与思考强度

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

  • 标准推理(Standard):适合日常简单提问、文档编写与小型函数编写,速度最快。

  • 深度思考(Deep Thinking):开启类似 o1/R1 级别的超长思维链,专门攻克大型复杂系统架构与疑难并发 Bug。


三、上手流程:从零到第一个完整项目

下面演示如何使用 ZCode 从零搭建一个支持多项目管理、数据本地持久化的高颜值待办事项系统 [1]。

第一步:新建或打开项目

在主界面点击「创建项目(Create Project)」或「打开已有文件夹」[1]:

图 9 创建项目

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

第二步:输入目标并启动

在输入框输入自然语言需求:

"帮我开发一个模块化的任务看板应用(Vue 3 + Vite)。要求包含待办、进行中、已完成三栏看板,支持卡片拖拽交互,支持按优先级设置颜色标签,数据自动写入 LocalStorage。"

第三步:审查代码 Diff 视图

ZCode 会自动启动规划流,并在右侧呼出标准的代码差异审查视图(Diff View)[3]:

图 10 Diff视图

图源:[3] AI一手《ZCode 零基础教程:国产 GLM-5.2 Coding Agent,从安装到真正干活(保姆级全攻略)》

绿色高亮新增代码,红色高亮删除部分。点击「Approve All」批量合并入本地仓库 [3]。

第四步:交付成果与自动化测试

构建完成后,ZCode 会在界面上呈递最终的交付看板,并附带功能核对清单:

图 11 待办清单成果

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

直接在本地双击预览或通过内置终端 npm run dev 启动,全部功能开箱即用 [1]。


四、核心功能与进阶

1. 重点:接入第三方模型与 API Key 配置

ZCode 并不自我封闭,除了自家的 GLM 模型外,官方在设置中内置了开放的提供商目录,支持一键挂载国内外各大模型平台 [1][3]。

(1)添加第三方提供商向导

进入「设置 → 模型与供应商(Providers)」点击添加 [1]:

图 12 添加供应商列表

图源:[1] 小林AI编程《保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例》

(2)配置 DeepSeek / 硅基流动接口示例

选择「自定义供应商」,填入对应参数 [3]:

图 13 DeepSeek自定义供应商

图源:[3] AI一手《ZCode 零基础教程:国产 GLM-5.2 Coding Agent,从安装到真正干活(保姆级全攻略)》

  • 供应商名称:DeepSeek

  • 接口地址 (Base URL):https://api.deepseek.com/v1

  • API Key:sk-xxxxxxxxxxxxxxxxxxxxxxxx

  • 模型名称:deepseek-chat, deepseek-reasoner

(3)配置文件模式(~/.zcode/config.json)

除了界面配置,ZCode 的配置也可以通过 JSON 直接管理:

json
{
  "current_model": "zhipu/glm-5.2-coding",
  "providers": {
    "zhipu": {
      "type": "official",
      "api_key": "env:ZHIPUAI_API_KEY"
    },
    "deepseek": {
      "type": "openai_compatible",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "env:DEEPSEEK_API_KEY",
      "models": ["deepseek-chat", "deepseek-reasoner"]
    },
    "local_ollama": {
      "type": "openai_compatible",
      "base_url": "http://localhost:11434/v1",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:7b"]
    }
  }
}

2. 下班挂机利器:闲时任务(Off-Hours Task)

很多开发任务需要耗费数小时(如全套测试回归、全代码库类型迁移、抓取几千份 PDF 文档)。ZCode 创新性地推出了「闲时任务」机制 [5]:

在右下角点击「新建闲时任务」:

图 14 新建闲时任务

图源:[5] 刺激AI《下班了,让 AI 替你熬夜 ZCode 闲时任务上手指南》

  • 设定触发时间(如下班后的 20:00)或触发条件(CPU 处于空闲状态时);

  • 勾选全自主模式,并指定目标 Git 分支;

  • 第二天上班打开电脑,ZCode 已经将包含测试通过报告、代码 Diff 的成果汇总完整打包呈现,实现了真正的「让 AI 替你熬夜」[5]!


3. 一键切换:Office 办公与科研模式

在界面左上角模式切换器中,点击「切换办公模式」[6]:

图 15 切换办公模式

图源:[6] 欧巴聊AI《实测ZCode办公模式,智谱给Office上科技了》

  • 文档排版与生成:不仅能读写 Word、Excel、PPT,还能通过自然语言清洗杂乱的考勤数据、自动绘制财务透视表 [6]。

  • 科研文献分析(Workflow 编排):支持批量导入上千份学术 PDF,自动执行文献综述、数据提炼与综述报告生成 [7][8]:

图 16 Workflow运行确认

图源:[8] 挖挖GitHub《我用 ZCode 在几千份文件中总结出了 AI 的发展态势!》


4. 插件中心与远程控制(BotChannel)

  • 丰富的插件中心:在设置页面中可以浏览并一键安装格式校验、数据库客户端、REST 测试套件等扩展 [6]:

图 17 插件页

图源:[6] 欧巴聊AI《实测ZCode办公模式,智谱给Office上科技了》

  • BotChannel 远程控制:在设置中绑定企业微信或飞书 Webhook 密钥,你可以在手机上直接向机器人发消息,遥控工位上的 ZCode 启停任务 [3]:

图 18 远程控制与BotChannel

图源:[3] AI一手《ZCode 零基础教程:国产 GLM-5.2 Coding Agent,从安装到真正干活(保姆级全攻略)》


五、避坑与注意(⚠️ 关键避坑)

1. ⚠️ 「编程套餐」与「开放平台 API」的额度陷阱

  • 问题:许多用户购买了智谱开放平台 BigModel 的通用 Token 资源包,但在 ZCode 客户端内依然提示套餐到期;或者反之,购买了 ZCode 客户端编程套餐,却无法在自己写的 Python 脚本里调 API [1][10]。

  • 注意:ZCode 客户端专属「编程套餐」(如图 04)是客户端内的定额畅享服务,而开放平台 API Key(如图 06)是按 Token 计费的公有云接口。两者钱包独立,不可直接混用,购买前务必按需认清![1]

2. ⚠️ 闲时任务必须绑定独立 Git 分支

  • 风险:在开启全自主闲时任务让它通宵重构时,如果工作区处于主干 main 分支且有未提交的临时修改,一旦任务中途因依赖冲突异常退出,会增加代码梳理成本 [5]。

  • 最佳实践:执行闲时任务前,先让它自动创建新分支 git checkout -b feature/idle-refactor,次日人工复核无误后再 Merge 回主分支 [5]。

3. ⚠️ 办公模式在 Linux / Docker 下的依赖缺失

  • 现象:在 Linux 服务器上运行办公模式生成 Word 或 PPT 时抛出 soffice conversion failed 异常 [6]。

  • 解决:这是由于 Linux 环境缺少文档渲染后端,终端执行 sudo apt install libreoffice-nogui 安装无头引擎即可彻底修复 [6]。


六、参考原文与出处

1. 本文参考微信公众号素材清单

#文章标题与链接来源公众号发布日期配图数为什么入选与核心引用点
1[保姆级教程:快速入门智谱 AI 编程工具 ZCode,附网站案例]小林AI编程2026-10-222929 张图保姆级入门,详细展示全部下载页、欢迎页三种连接、编程套餐、BigModel配置、思考强度、待办清单实战(引用图 01、03、04、05、06、08、09、11、12)
2[如果你用不了Codex,那我推荐试试它的国产平替,智谱Zcode保姆教程来了]墨玩AI2026-06-283131 张图系统介绍,重点讲解 Skills 软链接迁移向导与环境搭建(引用图 02)
3[ZCode 零基础教程:国产 GLM-5.2 Coding Agent,从安装到真正干活(保姆级全攻略)]AI一手2026-07-025151 张图长文攻略,深入演示 DeepSeek 自定义供应商、自动编辑权限、Diff 视图与 BotChannel 远程控制(引用图 07、10、13、15)
4[新手入门:如何配置 ZCode]RenderlessAI2026-07-155新手配置指南,梳理网络设置、模型选择与快捷键映射
5[下班了,让 AI 替你熬夜 ZCode 闲时任务上手指南]刺激AI2026-08-205独家特色玩法,详细剖析「闲时任务」的创建、定时触发与次日交付流程(引用图 16)
6[实测ZCode办公模式,智谱给Office上科技了]欧巴聊AI2026-10-211919 张图跨界评测,演示插件中心与一键切换办公模式处理 Office 报表(引用图 14、17)
7[国产科研神器?AI工作台ZCode实测!]瑞侠AI智能体2026-11-011科研人员实测,评测文献综述、自动化数据清洗与组会 PPT 报告生成
8[我用 ZCode 在几千份文件中总结出了 AI 的发展态势!]挖挖GitHub2026-10-2218海量文件多模态挖掘实操,演示长工作流(Workflow)编排与运行(引用图 18)
9[DeepSeek Harness 和 ZCode 到底哪个好用?(3轮深度实测)]AI洛兹克2026-10-1118权威同题横评,从代码质量、速度、上下文容错三轮维度对比两大国产顶流
10[我本来把 ZCode 当 Codex 平替,用了 24.7 亿 Token 后,我改了看法]说明书外2026-10-12224.7 亿 Token 极限长周期压测,客观总结 ZCode 的稳定极限与工程化心智演进

2. 官方技术文档与生态规范列表

编号来源与页面名称查阅日期补充与核实用到的核心内容
[官1]智谱 BigModel 开放平台技术标准 (open.bigmodel.cn)2026-11-08GLM-5.2 系列模型上下文规范、编程专属套餐协议与 API 计费字典
[官2]ZCode 架构与权限规范 RFC2026-11-08普通模式、自动编辑与全自主模式沙箱安全机制
[官3]ZCode BotChannel 远控协议规范2026-11-08外部即时通讯机器人(企微/飞书)通过 Webhook 安全通信加密协议
[官4]ZCode Off-Hours Task 调度器技术说明2026-11-08闲时任务后台唤醒、锁保护与 Git 工作区隔离策略

3. 本文使用图片清单核对表

图片文件名图片内容说明引用章节对应素材来源
01-全部下载页.png官方全平台安装包(Win/Mac/Linux)下载页第一节 定位[1] 小林AI编程
02-迁移向导Skills软链.png首次启动时的 Claude Code/Codex 技能迁移向导第二节 2. 客户端安装与生态迁移[2] 墨玩AI
03-欢迎页三种连接.png欢迎界面的三种连接方式(官方/API/自定义)第二节 1. 账号体系与连接方式[1] 小林AI编程
04-模型设置与编程套餐.png智谱账号绑定的编程套餐详情与模型列表第二节 1. 账号体系与连接方式[1] 小林AI编程
05-添加供应商列表.png模型设置中的第三方供应商添加清单第四节 1. 接入第三方模型[1] 小林AI编程
06-BigModel-API配置.png智谱 BigModel 开放平台 API 密钥绑定弹窗第二节 1. 账号体系与连接方式[1] 小林AI编程
07-DeepSeek自定义供应商.png添加 DeepSeek 自定义 Base URL 与模型 ID第四节 1. 接入第三方模型[3] AI一手
08-模型与思考强度.png状态栏模型切换与思考强度(Thinking)滑块第二节 3. 权限与思考强度[1] 小林AI编程
09-权限模式含自主模式.png开启全自主模式(Autonomous Mode)选项第二节 3. 权限与思考强度[1] 小林AI编程
10-权限模式含自动编辑.png自动编辑(Auto Edit)安全权限切换菜单第二节 3. 权限与思考强度[3] AI一手
11-创建项目.png新建项目与选择工作区文件夹界面第三节 上手流程[1] 小林AI编程
12-待办清单成果.png自动化开发交付的待办清单应用成果看板第三节 上手流程[1] 小林AI编程
13-Diff视图.png代码变更审查的高对比度 Diff 视图第三节 上手流程[3] AI一手
14-插件页.jpgZCode 插件市场与已安装工具列表第四节 4. 插件中心与远控[6] 欧巴聊AI
15-远程控制与BotChannel.png绑定企业微信/飞书机器人的远程控制设置第四节 4. 插件中心与远控[3] AI一手
16-新建闲时任务.png新建夜间/离线自动执行的闲时任务窗口第四节 2. 闲时任务[5] 刺激AI
17-切换办公模式.jpg一键由编程模式切换为 Office 办公模式第四节 3. 办公与科研模式[6] 欧巴聊AI
18-Workflow运行确认.png多文件批量处理与科研工作流运行确认面板第四节 3. 办公与科研模式[8] 挖挖GitHub
更新于 2026-11-08来源:用户提供《工具指南_完整全套_含所有MD与图片.zip》;正文保留原文参考来源