ZCode 正式开源：桌面、Web、终端 Agent 一次开放！架构、功能与本地部署完整指南

ZCode 是 Z.ai 于 2026 年 9 月 20 日公开源码的 AI 编程工作台，统一提供 Electron 桌面应用、浏览器工作台、终端 TUI 与 Agent CLI，并公开客户端、后端服务、共享 UI 和 Agent 运行时。官方仓库当前版本为 3.14.0，采用 Apache License 2.0；源码已经开放，但 GitHub 尚无正式 Release 或 tag，普通用户与二次开发者应区分源码构建和发行包安装。

1. ZCode 正式开源了什么

ZCode 开源的是一套完整 AI 编程工作台，而不是单独的代码模型或只有聊天界面的客户端。

官方仓库包含三种主要入口：

入口	运行形态	适用场景
Desktop	Electron 桌面应用	本地项目、图形界面、远程工作区
Web / ZCode 命令行版	浏览器界面与本地后端	服务器、浏览器访问、统一发行包
Agent CLI	`zcode` 命令与 TUI	终端开发、脚本调用、Agent 运行时

仓库创建于 2026 年 9 月 20 日；截至 2026 年 9 月 21 日 GitHub API 显示约 3,521 Stars、912 Forks，主语言为 TypeScript（来源：GitHub Repository API，2026）。这些数字会持续变化，只能视为抓取时点快照。

根目录 package.json 标记版本 3.14.0，许可证为 Apache-2.0；mise.toml 固定 Node.js 24.14.0 和 pnpm 10.33.2（来源：zai-org/ZCode，2026）。官方 README 同时说明 Agent CLI 与运行时已作为普通目录包含在仓库中，不需要再初始化 Git submodule。

2. ZCode 的核心架构

ZCode 用 Monorepo 把桌面、Web、服务端、共享组件和 Agent CLI 组织在同一套工作区中。

主要目录职责如下：

packages/desktop：Electron Main、Host、Renderer 与桌面打包。
packages/web：浏览器客户端。
packages/server：HTTP、WebSocket 服务与远程连接。
packages/ui：共享 React 组件、Hooks 与 Zustand 状态。
packages/provider：模型 Provider 公共能力和 Node 实现。
apps/zcode-cli：Agent CLI、TUI、运行时与工具。

这套结构意味着桌面版、Web 版和终端版可以共享 Agent 能力，但三者的权限、文件位置、认证和网络行为并不完全相同。官方 NOTICE.md 特别提醒：Web 或远程工作区中的命令可能实际发生在服务端、SSH 主机、WSL 或容器中，不能只看当前页面所在设备判断执行位置。

3. 本地源码部署

源码部署适合二次开发和审计；只想使用产品的用户应优先等待或使用官方提供的签名发行物。

3.1 环境准备

先安装 Git、Node.js 24.14.0 和 pnpm 10.33.2，再克隆仓库：

git clone https://github.com/zai-org/ZCode.git
cd ZCode
node --version
pnpm --version
pnpm bootstrap

pnpm bootstrap 会安装 workspace 依赖、准备桌面本地运行资源，并执行 build:bootstrap。默认流程跳过远程资源准备，适合本地桌面开发；需要 SSH 或 WSL 远程功能时使用：

pnpm bootstrap:with-remote

依赖安装和构建脚本可能运行原生模块及生命周期脚本。处理不可信分支或 Pull Request 时，应在隔离账号、容器或一次性环境中构建。

3.2 启动桌面版

桌面开发入口分为生产服务配置和测试环境：

# 默认使用生产服务配置
pnpm dev:desktop

# 使用测试环境
pnpm dev:desktop:test

需要隔离开发数据时，可指定数据基目录：

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

该变量会把应用数据写入指定目录下的 .zcode/，适合避免开发会话污染日常配置。

3.3 启动 Web 版

Web 开发模式会同时启动前端和后端：

pnpm dev:web

官方默认地址是：

Web 开发服务器：http://localhost:5173
后端服务：http://localhost:3030

指定后端工作区时使用绝对项目路径：

ZCODE_SERVER_WORKSPACE=/absolute/path/to/project pnpm dev:web

/ws 和普通 /api 请求会代理到本地后端。开发服务不应未经认证直接暴露到公网。

4. 终端版和统一 `zcode` 命令

ZCode 命令行发行包把 TUI、Web 与 Agent 统一到一个命令中，无参数启动终端界面，--web 启动浏览器工作台。

# 进入终端交互界面
zcode

# 启动 Web 界面
zcode --web

# 指定项目、端口并禁止自动打开浏览器
zcode --web --workspace /absolute/path/to/project --port 3030 --no-open

zcode --help
zcode --web --help

Web 模式默认监听 127.0.0.1，并自动选择空闲端口。本机监听默认不启用访问令牌；使用 --host 0.0.0.0 监听非本机地址时，官方实现会默认生成访问令牌。即便如此，跨机器部署仍应增加 TLS、主机防火墙和反向代理访问控制。

直接启动通用 HTTP 服务时，可用 ZCODE_SERVER_AUTH_TOKEN 配置 API 与 WebSocket 认证。不要为了省事在公网环境使用 --no-token。

5. 如何构建发行包

桌面版与统一命令行版采用不同的打包入口，构建结果也不能互相替代。

5.1 桌面应用

# 默认构建 macOS arm64
pnpm bundle:desktop

# 指定 Windows x64
pnpm bundle:desktop -- --os win --arch x64

pnpm bundle:desktop -- --help

--os 支持 mac、win 和 linux，--arch 支持 x64 与 arm64。实际签名仍需要目标平台对应的证书和工具；本地未签名构建不等于官方可信发行物。

5.2 命令行发行包

pnpm build:zcode 会构建 CLI/TUI、后端和 Web，并组装统一运行包：

pnpm build:zcode --base-url https://downloads.example.com/zcode/

其中 https://downloads.example.com/zcode/ 是占位地址，发布时必须换成真实托管地址。输出位于 dist/zcode/，包括：

releases/<version>/zcode-<version>.tar.gz
releases/<version>/sha256.txt
latest.json
install.sh

安装脚本默认把运行时放在 ~/.zcode/runtime，并在 ~/.local/bin 创建 zcode 命令。构建动作不会自动替换 PATH 中已有的同名命令，可用 command -v zcode 或 Windows 的 where.exe zcode 检查实际入口。

6. 配置 Provider、插件与 MCP 时要注意什么

ZCode 支持 Provider 配置、插件、Skills、Hooks 和 MCP，但这些扩展可能读取文件、运行进程、访问网络或把工具参数发送给远端服务。

配置文件的主要环境变量包括：

变量	用途
`ZCODE_DATA_BASE_DIR`	应用数据基目录
`ZCODE_SERVER_WORKSPACE`	Web 后端工作区路径
`ZCODE_BUILTIN_PROVIDER_CONFIG_FILE`	本地 Provider 配置文件路径
`ZCODE_DIST_BASE_URL`	命令行安装包下载根地址

模型端点、密钥和 MCP 认证信息应放在未跟踪的本地配置或密钥服务中。若需要在正式接入前对比多款主流大模型的输出，可以使用七牛云 AI 的模型对比能力作为外部测试基线；是否能直接配置为 ZCode Provider，仍应以当前 Provider Schema 和接口兼容性测试为准。

官方 NOTICE.md 明确说明，工作区级 MCP 可被纳入自动连接范围，stdio Server 会在本地或实际执行主机启动进程，HTTP/SSE Server 会向配置地址发送请求。启用任何插件或 MCP 前，应检查命令、环境变量、认证头、OAuth 权限和工具副作用。

7. 开源是否意味着可以直接商用

Apache License 2.0 允许使用、修改和分发源码及衍生作品，但再分发时需要保留许可证、修改声明、版权与 NOTICE 中适用的归属信息。

需要分别核对三层许可：

ZCode 主仓库的 Apache-2.0 条款。
third-party 目录记录的第三方组件许可证。
实际使用的模型、插件、MCP Server 和在线服务条款。

开源客户端不代表模型调用免费，也不代表所有内置在线服务可以私有化部署。仓库源码能核验客户端行为，但无法覆盖外部网关或业务服务内部实现。

8. 安全边界与常见问题

Q：ZCode 开源的是模型吗？
不是。该仓库是 AI 编程工作台和 Agent 运行时，模型能力由实际 Provider 或服务端提供；不能把 ZCode 与某个代码模型等同。

Q：为什么执行 pnpm bootstrap 后仍不能启动？
先核对 Node.js 24.14.0 与 pnpm 10.33.2，再检查原生依赖构建和桌面运行资源。远程工作区还需要 pnpm bootstrap:with-remote。

Q：仓库版本 3.14.0 是否等于已有稳定 Release？
不等于。截至 2026 年 9 月 21 日，GitHub Releases 最新接口返回 404，tags 列表为空；3.14.0 来自源码根目录 package.json，不是 GitHub Release 证明。

Q：局域网能直接使用 zcode --web 吗？
可以监听 0.0.0.0，但必须保护终端输出的令牌，并增加 TLS、防火墙和访问控制。工作区文件与 Agent 工具会在服务进程权限范围内运行。

Q：Agent 显示“已完成”是否可信？
只能作为状态提示。官方声明要求结合文件、命令退出状态、工具结果和测试核查；重要操作还应保留可恢复备份。

9. 是否值得现在部署

希望审计 Agent 运行时、开发桌面/Web/终端一体化编程工作台，或需要定制 Provider、插件与 MCP 的团队，可以从源码开始评估 ZCode。只需要稳定成品的普通用户，应优先使用签名发行物，并等待明确的 Release、升级和兼容性说明。

ZCode 正式开源的价值在于把桌面端、Web 服务、TUI、Agent CLI 和共享运行时放进同一个可审计仓库，而不仅是开放一层 UI。根据 Z.ai 官方仓库、GitHub API、Apache-2.0 许可证和 NOTICE.md，项目已经开放源码，但 GitHub 尚无 Release 或 tag，权限与数据边界也因运行形态而异。本文内容基于 2026 年 9 月 21 日资料，版本、Stars 和发行状态应在部署前重新核对。

延伸资源

ZCode 官方仓库：https://github.com/zai-org/ZCode
ZCode 官网：https://zcode.z.ai/
Apache License 2.0：https://github.com/zai-org/ZCode/blob/main/LICENSE
项目风险与第三方声明：https://github.com/zai-org/ZCode/blob/main/NOTICE.md
七牛云AI 大模型广场（含GLM模型）：https://www.qiniu.com/ai/models