---
url: /zcode/introduction.md
description: >-
  ZCode 是智谱 Z.ai 于 2026 年 9 月 20 日开源的 AI 编程工作台（Apache-2.0，当前
  v3.14.3），一次放出桌面应用、Web 客户端、后端服务与 Agent CLI 全部源码。它带 Goal Mode
  目标模式、四档执行模式、内置浏览器自动化、SSH/WSL/Docker 远程开发、Subagent 与动态多智能体工作流，支持 Skills /
  Commands / MCP / Hooks 扩展，可接 GLM Coding
  Plan、Anthropic、OpenAI、OpenRouter、Moonshot、MiniMax、小米 MiMo
  等任意兼容端点。本文带你从"它为什么开源"讲到本机跑起来。
---

# 认识 ZCode：被骂"偷偷上传代码"的第 3 天，智谱把整个 AI 编程工作台开源了

先讲一件有点黑色幽默的事。

2026 年 9 月 19 日，有开发者发现智谱的 AI 编程产品 **ZCode** 在生成 Repo Wiki 的时候，会把本地代码仓库打成一个快照、加密上传到阿里云对象存储。

社区炸了。这触碰的是程序员最敏感的那根神经——**我的代码仓库，你凭什么传走？**

然后剧情拐了个弯，拐得有点猛：

* 9 月 19 日：官方发情况说明、致歉，披露原因和整改方案，**承诺开源 ZCode 代码库**，并给全体用户额外重置一次周额度；
* 9 月 21 日：宣布整改完成，**ZCode 正式开源，Apache-2.0 协议**，把代码交给社区监督；
* 同日：公布**中国信息通信研究院（CAICT）与绿盟科技（NSFOCUS）**的审计结果——`zcode-prod` 这个阿里云 OSS 存储桶为**云端零数据**，全部数据对象及存储桶本身已清除；v3.14.0 客户端**移除了 Repo Wiki 功能及相应生成链路**；
* 9 月 28 日：新一轮补偿方案，付费用户给 8 张重置卡，全体用户连续 10 天发放 Token。

我盯着这个时间线看了半天，脑子里只有一个念头：

**一个 AI 编程工具把自己整个工作台——桌面应用、Web 客户端、后端服务、Agent 运行时——全开源了，起因是一次信任事故。**

这大概是 2026 年我见过最"实在"的道歉方式。PPT 和承诺书都能写，源码不能。

而且说实话，这件事背后有个更值得聊的判断：\*\*当 AI 编程 Agent 能读你的文件、跑你的终端、动你的 Git、还能联网，你就必须能读到它的每一行源码。\*\*否则"它到底干了什么"这个问题，永远只能靠厂商自证。

## 什么是 ZCode

**ZCode 是智谱（Z.ai / Zhipu AI）的 AI 编程工作台（Agentic Development Environment，ADE），2026 年 7 月正式发布，2026 年 9 月 20—21 日以 Apache-2.0 协议开源（仓库：`zai-org/ZCode`，当前版本 **v3.14.3**）。它不是一个"聊天窗口 + 代码补全"，而是一个把任务上下文、文件读写、终端、Git、权限、浏览器、远程主机全部收进同一个任务里的 Agent 运行环境，一次提供桌面应用（Electron）、浏览器界面和终端 Agent（CLI / TUI）三种形态。**

先把"它不是什么"说清楚：

* 它**不是**一个模型。它是跑模型的那一层壳——模型你可以自己选，见下文；
* 它**不是**插件。它是独立的工作台，桌面版自带文件树、任务列表、终端、Git 控制、Review、内置浏览器；
* 它**不是**"开源了个空壳"。仓库里 `packages/desktop`（Electron）、`packages/web`、`packages/server`（HTTP / WebSocket）、`packages/zcode-server-cli`、`packages/ui`、`packages/services`、`packages/shared` / `rpc` / `client`、`packages/provider`，以及 `apps/zcode-cli`（Agent CLI、TUI、运行时与工具）全都在，而且 **Agent CLI 是普通目录，不是 submodule，克隆下来就能跑**。

这次开源的完整仓库结构，官方 README 里列得很直白：

| 目录 | 职责 |
|---|---|
| `packages/desktop` | Electron Main、Host、Renderer 与桌面打包 |
| `packages/web` | Web 客户端 |
| `packages/server` | HTTP / WebSocket 服务与远程连接 |
| `packages/zcode-server-cli` | 独立 Server 启动与进程管理 |
| `packages/ui` | 共享 React 组件、hooks 与 Zustand 状态 |
| `packages/services` | 业务服务与持久化 |
| `packages/shared` / `rpc` / `client` | 共享协议和类型、RPC 框架、Agent 客户端 SDK |
| `packages/provider` / `provider-node` | Provider 公共能力与 Node 实现 |
| `apps/zcode-cli` | Agent CLI、TUI、运行时与工具 |
| `scripts` / `config` / `third-party` | 构建维护脚本、内置配置与第三方声明材料 |

技术栈是 **TypeScript + pnpm workspace monorepo**，版本钉死在 **Node.js 24.14.0 + pnpm 10.33.2**（写在 `mise.toml` 里）。截至 2026 年 9 月 24 日前后，仓库约 **6.8k Star、2k Fork**。

> 我一直觉得，"AI 编程工具"这个品类的终局不是谁的模型更聪明，而是**谁来定义你和 Agent 说话的那个界面**。
> 智谱给出答案的方式很直接：不只是卖 GLM 的 API，而是自己把桌面端、Web 端、CLI 全做了，然后把整套东西开源。
> 这是 Claude Code、Codex CLI、Cursor 那条赛道上的第 N 个玩家，但它是第一个把源码摊开的国产选手。

## 它有什么特点

* **Goal Mode：给 Agent 一个"完成条件"，它自己一轮轮干到通过为止。** 这是我认为 ZCode 最有辨识度的设计。

  你在会话里敲一句：

  ```
  /goal make pnpm test pass
  ```

  Agent 就有了可以自查的目标：每轮结束后自己跑一遍验证，没过就再开一轮。什么时候停？**验证通过、你手动暂停或清除目标、或者跑到了你配置的用量预算。**

  > 这解决的是 Coding Agent 最烦人的那个体验：你交代一个任务，它改了七轮，最后一脸真诚地说"应该可以了"。
  > 有了 Goal Mode，"应该可以了"变成一个**可被机器判定的条件**。这一下就把 Agent 从"陪聊"推进到"交付"。

* **四档执行模式，权限粒度是真的在给。** 不是笼统一个"YOLO 开关"：

  | 模式 | 行为 |
  |---|---|
  | **Ask before changes** | 每次改文件、每次跑命令都要你确认（**默认模式**） |
  | **Edit automatically** | 文件修改自动执行，但命令仍需确认 |
  | **Plan** | 先分析项目，等你批准方案后再开工 |
  | **Full access** | 减少确认提示，给可信任务用 |

* **内置浏览器：前端任务能闭环。** 桌面版自带浏览器面板，Agent 可以打开你的本地 dev server 或线上页面，**点按钮、填表单、滚动、截图**。也就是说一个前端需求，从改代码到看渲染结果，可以在同一个任务里跑完，不用你自己在浏览器里点一遍再回来骂它。

* **远程开发：项目可以不住在本机。** 文件访问、终端命令、Git 操作、Agent 执行，整体搬进 **SSH 主机、WSL 发行版或本地 Docker** 里跑；桌面客户端继续管你的账号、模型配置和任务控制。

  这对"代码必须留在内网 / 开发机"的团队非常关键——顺带说一句，考虑到这次事故的起因，**远程开发 + 源码可审**这个组合，大概正是很多团队现在最想看到的形态。

* **Subagent + 动态多智能体工作流。** 内置 general-purpose 和 Explore 两类子智能体，自定义或插件子智能体可以各自定义指令和模型。更大的活可以用一份 workflow 定义去协调多个 Subagent，而且 **v3.14.3 起，运行中的工作流并发数可以直接调，不用停任务**。

  v3.14.3 的 Release Notes 里还有几条很"工程"的改进，我挺喜欢的：**工作流脚本提交与修改的 token 消耗降低了**、**大工作流的实时状态显示改好了**、**修掉了工作流把界面搞崩的问题**。看得出来是真有人在天天用。

* **扩展点很全：Plugins / Skills / Commands / MCP / Hooks。**

  * 一个 **Plugin** 可以打包 Skills、Commands、Subagents、MCP servers 和 Hooks；
  * **Skills** 用 `SKILL.md` 写可复用流程（代码审查、生成 Release Notes 之类）；
  * **Commands** 存更短的提示词动作；
  * **MCP** 支持 stdio / HTTP / SSE 三种传输，而且**能直接从 Claude Code、Codex CLI、OpenCode 导入已有 MCP 配置**——这一手很聪明，迁移成本几乎归零；
  * **Hooks** 可以在会话启动、提示提交、工具调用、权限请求、失败、任务完成这些事件周围挂本地进程。

  扩展还能按 **user 或 workspace 两种作用域**存放，团队可以共用一套。

* **模型随便换，不绑死 GLM。** 官方列的接入清单：

  **GLM Coding Plan、Z.ai / BigModel API、Anthropic、OpenAI、OpenRouter、Moonshot（月之暗面）、MiniMax、Xiaomi MiMo**，以及任何实现了 **Anthropic 兼容或 OpenAI 兼容**的自定义端点。

  ZCode Agent 对 GLM-5.3 和 GLM-5.3-Flash 做了深度调优（8 月 27 日 ZCode 接入刚开源的 GLM-5.3-Flash，并深度适配 GLM-5.2），依托 **1M 长上下文**支撑从规划、编码、审查到迭代的全流程。

* **三端同一套运行时，免 Electron 也能跑。** 命令行发行包把 TUI、Web、Agent 打包进一个 `zcode` 命令：

  ```bash
  zcode                 # 无参数 → 进入终端 TUI
  zcode --web           # 启动本地 Web 界面
  ```

  Web 模式默认只监听 `127.0.0.1`、默认不启用访问令牌、自动选空闲端口并打开浏览器；想局域网访问就 `--host 0.0.0.0`，**此时默认生成访问令牌**并在终端打印带 token 的链接。可以用 `--token` 自己指定，或 `--no-token` 关掉。

  桌面版支持 **macOS / Windows / Linux**，v3.14.3 的安装包是 `ZCode-3.14.3-mac-arm64.dmg`（177 MB）和 `ZCode-3.14.3-win-x64.exe`（143 MB）。

## 用在哪儿

**长任务改造：给老项目加测试、做迁移、修一串 lint。** 这类活的特点是"轮次多、标准明确"。Goal Mode 正好对上——`/goal make pnpm test pass`、或者 `/goal` 加上"某目录下不再出现某个 deprecated API"。有明确的判定条件，Agent 才知道自己该不该停。

**前端开发闭环。** 改组件 → 起 dev server → 内置浏览器打开页面 → 点一遍 → 截图看效果 → 回去再改。以前这是"人肉在浏览器和编辑器之间来回切"的活，现在能收在一个任务里。

**内网 / 远程开发机上的项目。** 代码不能出内网的团队，用 SSH 远程开发把 Agent 执行放在远端，本地客户端只管账号、模型与任务控制。**但请务必先读完 NOTICE.md**——功能范围、维护规则、执行与数据风险都写在那里，这次的事故就是最好的提醒。

**需要接内部系统的团队。** MCP + Hooks + Skills 三件套，是把它塞进公司现有流程的入口：MCP 接内部服务，Hooks 在权限请求和任务完成时挂你的审批逻辑，Skills 把团队的代码规范和发布流程固化成 `SKILL.md`。

**不想被单一模型绑死的人。** 你今天用 GLM Coding Plan，明天想试 MiMo 或者自建的 vLLM 端点，改个配置就行。对成本敏感的场景，这个自由度很值钱。

**不适合的地方也说清楚**：

* 想要"装完就能白嫖"的同学——**ZCode 应用本身免费开源，但模型是按你接的账号、Coding Plan、API Key 或第三方服务计费的**。开源的是工作台，不是算力；
* 浏览器自动化**只在桌面版有**；
* 远程同步会传输部分开发资源与配置（开发态经 SFTP 上传），**敏感配置同步前请自己过一遍**；
* 用私有仓库的同学，务必逐项确认：你选的模型服务商、执行模式、启用的扩展、远程主机是否可信，以及每个功能的数据流向。

## 初体验

**路线 A：不折腾，直接用桌面版 / CLI 发行包。**

去 GitHub Releases 下 v3.14.3 对应平台的安装包，macOS 拖进"应用程序"即可。本地构建的产物没签名，被 macOS 拦截时执行：

```bash
sudo xattr -rd com.apple.quarantine /Applications/ZCode.app
```

**路线 B：从源码跑起来（推荐，既然都开源了）。**

```bash
git clone https://github.com/zai-org/ZCode.git
cd ZCode

# 环境：Git + Node.js 24.14.0 + pnpm 10.33.2（以 mise.toml 为准）
pnpm bootstrap      # 装 workspace 依赖 + 准备桌面本地资源 + 执行 build:bootstrap

pnpm dev:desktop    # 起桌面版（Electron + 源码监听）
pnpm dev:web        # 起 Web 开发态：前端 5173、后端 3030
```

CLI 单独开发：

```bash
pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

# 构建 CLI 及其 workspace 依赖
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help
```

**路线 C：只想最快验证 CLI 全链路。**

```bash
# 本地解压运行，不需要上传也不需要安装
zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" -C dist/zcode/debug

node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open
```

然后浏览器打开 `http://127.0.0.1:3030`，Web 页面和 Agent 由同一个后端服务托管，一条链路全都验证到了。

**几个你会立刻用到的环境变量：**

| 变量 | 用途 |
|---|---|
| `ZCODE_DATA_BASE_DIR` | 应用数据基目录，数据写入其下的 `.zcode/` |
| `ZCODE_SERVER_WORKSPACE` | Web 后端的工作区路径 |
| `ZCODE_BUILTIN_PROVIDER_CONFIG_FILE` | 本地 Provider 配置文件路径；不设则用内置配置 |
| `ZCODE_DIST_BASE_URL` | 命令行安装脚本的下载根地址 |

**四个坑，提前给你标出来：**

**第一，Node.js 和 pnpm 版本是真的钉死的。** 24.14.0 / 10.33.2，写在 `mise.toml` 里。别拿你机器上那套老环境硬跑，先装 mise 或者 nvm 切版本。

**第二，旧 Lite 用户要迁移。** 官方明确说了：Lite 用户必须改用新的构建命令、环境变量和新安装脚本，而且**新安装不会删除旧 Lite 目录，也不会迁移或删除已有会话数据**。想清干净，自己动手。

**第三，`pnpm build:zcode` 不会替换 PATH 里已有的 `zcode`。** 构建完如果命令还指向旧安装，用 `command -v zcode`（Windows 用 `where.exe zcode`）查一下。这个坑我敢说十个人里有八个会踩。

**第四，安全那根弦别松。** 就算源码开源了、审计报告也出了，**"Ask before changes" 永远是默认模式这件事本身就说明了官方的态度**。别一上来就切 Full access，尤其是接了第三方 MCP server 或连了不明远程主机的时候。

## 进阶

如果这篇文章你只记住一件事，我希望是这个判断：

**AI 编程工具的下半场，竞争的不是模型，是"你敢不敢把权限交出去"——而这件事最终只能靠开源和可审计来解决。**

我们这一年看着 Coding Agent 的权限越来越大：读文件、写文件、跑命令、动 Git、开浏览器、连远程主机。能力每加一项，风险就加一档。到今天，"Agent 到底对我的代码做了什么"这个问题，闭源产品只能给你一份承诺书；而 ZCode 这次给的是 **Apache-2.0 的仓库、一份第三方审计报告，和一个已经删掉的上传链路**。

冷水照例要泼：

**第一，开源不等于无风险。** 源码摊开只是让你能审，不等于你审了。私有仓库用户仍然要自己确认模型服务商的数据处理方式——智谱也承诺了 MaaS 平台将支持申请 **no-retention**（标准模型调用的输入输出不做静态存储，仅用于当前请求），但 **Batch API、File API 以及出于法律、安全与滥用防控需要保留的信息，仍可能按一定期限留存**。

**第二，这是一次事故驱动的开源，不是产品规划的自然结果。** 好处是诚意足、动作快；隐忧是仓促——仓库开源初期只有三个 commit，文档以中文为主，构建链条（Node 版本、远程资源、mock-cdn、SFTP 上传）对新人不算友好。**把它当"能用的工作台"，别当"成熟的社区项目"。**

**第三，成本在模型侧。** 工作台免费，但你跑 Goal Mode 一轮轮迭代，烧的是 token。v3.14.3 专门优化了"工作流脚本提交与修改的 token 消耗"，本身就说明这块是真实痛点了。**上 Goal Mode 之前先设好用量预算。**

我的建议很具体：\*\*如果你在用 Claude Code 或 Codex CLI，今天就可以花半小时试一下——直接从它们导入现有 MCP 配置，接一个你已经付费的模型端点，挑一个"有明显判定条件"的任务（比如让某个目录下的测试全绿）开 Goal Mode，然后只看两件事：它几轮收敛，以及最后是不是真的自己验过了。\*\*这两件事决定 ZCode 值不值得进你的日常工具箱，比任何宣传稿都准。

再往深一层，我建议你去读仓库里三个文件：**`DESIGN.md`**（架构取舍）、**`AGENTS.md`**（Agent 的行为约定）、以及 **`NOTICE.md`**（功能范围与数据风险）。尤其是 `NOTICE.md`——一个愿意把"执行与数据风险"单独写成一份声明的项目，值得你认真读完再决定要不要把代码交给它。

更多开源技术干货和学习资料，关注公众号「遇码」，领取专属福利。