# 在电脑上运行你的第一个智能体：ZCode 安装与配置

> ZCode 是智谱推出的智能体开发环境（ADE）—— 说白了，就是把 Agent 嵌进编辑器和终端的工作台。想在电脑上跑起第一个智能体，其实只要两件事：装个客户端、接个模型。 这篇分两半：前半是怎么装…

- 原文：https://wanrenhuifu.github.io/blog/install-and-configure-zcode/
- 发布：2026-09-13
- 部门：技术部
- 标签：ZCode、DeepSeek、AI、教程
- 字数：6102
- 许可：https://creativecommons.org/licenses/by-nc-sa/4.0/（署名—非商业性使用—相同方式共享）
- 站点：https://wanrenhuifu.github.io/

---

ZCode 是智谱推出的智能体开发环境（ADE）—— 说白了，就是把 Agent 嵌进编辑器和终端的工作台。想在电脑上跑起第一个智能体，其实只要两件事：装个客户端、接个模型。

这篇分两半：前半是怎么装、怎么接模型（含一条**第三方 API 的完整走法，用 DeepSeek 举例**）；后半是配置该放哪。后者更容易绕晕，因为 ZCode 的扩展资源有两个作用域、五种类型，还各带一套覆盖规则。版本号以 **v3.11.2** 为准。

## 五分钟路径

只想先跑起来，照这五步走（细节都在下面各节）：

1. **下载安装** —— [官网](https://zcode.z.ai/cn)取对应平台的包，Windows **右键 → 以管理员身份运行**。
2. **启动** —— 点「开始使用 ZCode」，数据迁移那一步跳过。
3. **选工作区** —— 随便挑个项目文件夹，以后再换不迟。
4. **连模型** —— 二选一：**连接 BigModel**（左下角「连接使用」→ 登录 → 回供应商列表**打开启用开关**，步数最少）；或**用 DeepSeek 的 API Key**（先拿 Key，再「设置 → 模型设置 → 添加供应商」，要填的几项见 3.2）。
5. **验证** —— 发一句「列一下当前目录的文件」，有回复就成了。

正式配之前先确认一件事：**代理**。网络走代理的话必须在「设置 → 常规」里手动填，**留空不等于跟随系统代理** —— 这是最容易让人误判成「账号有问题」的地方（见第三节）。

## 一、安装前确认

支持 **macOS**（Apple Silicon / Intel，`.dmg`）、**Windows**（x64 / ARM64，`.exe`）、**Linux**（x64 / ARM64，`.AppImage`、`.deb`、`.rpm`）。

不需要预装 Node.js。唯一和外部工具有关的是 Windows 上的终端选择：ZCode 默认**优先用 Git Bash，找不到就回退 `cmd.exe`**，所以想让 Agent 用上 Git Bash 就先把 Git 装好。

安装包从[官网](https://zcode.z.ai/cn)下载，文件名带版本号（如 `ZCode-3.11.2-win-x64.exe`），别照抄版本号，以官网当页为准。

## 二、安装

**Windows** —— `.exe` **右键 → 以管理员身份运行**，按向导走完，再从开始菜单或桌面快捷方式启动；ARM64 机器选 `-win-arm64.exe`。这一步别省：直接双击在部分环境下会因权限不足中断或组件写入失败，而失败常发生在向导中途、看不出原因。装完之后日常启动不需要管理员权限。

**macOS** —— 打开 `.dmg`，把 `ZCode.app` 拖进「应用程序」，从启动台启动。Apple Silicon 与 Intel 是分开的两个包，选错跑不起来。若提示「已损坏，无法打开」，那是 Gatekeeper 的隔离标记，不是文件坏了：

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

**Linux** —— `.AppImage` 先加可执行权限：

```bash
chmod +x ZCode-*.AppImage
./ZCode-*.AppImage
```

`.deb` / `.rpm` 用发行版自带的包管理器装即可；少数发行版还需单独装 `fuse`，否则 AppImage 起不来。

## 三、首次启动与连接模型

第一次打开是「首次启动设置」：选**开始使用 ZCode** 直接进入；**数据迁移向导**目前仅支持导入 Claude Code 与旧版 ZCode 中 ZCode Agent 的对话记录，也可以先跳过、之后在设置里再迁。接着选一个本地项目目录作为**工作区**。

> **动手连模型之前先检查代理。** 网络依赖代理时要在「设置 → 常规」里手动配置，**留空不等于跟随系统代理**。不填的典型症状是模型连不上、但账号状态看起来完全正常 —— 很容易误判成账号问题。下面两种连接方式都受它影响。

### 3.1 用官方账号连接

没配模型时，点左下角「连接使用」进入登录页，三种方式：**连接 Z.ai**（官方账号）、**连接 BigModel**（国内账号，无需海外支付，国内用户走这条更顺）、**使用 API Key**（自带 Key）。

### 3.2 接一个第三方 API：以 DeepSeek 为例

ZCode 支持任何兼容 OpenAI 或 Anthropic 协议的服务 —— 自定义供应商本质上就是填一个地址、一个 Key、一串模型 ID。

**第一步：在开放平台拿到 API Key**

打开 [DeepSeek 开放平台](https://platform.deepseek.com)：

1. **登录** —— 手机号或微信扫码，没注册过的会自动注册。
2. **完成实名认证** —— 没做这步无法充值、也无法创建密钥。
3. **充值** —— 左侧「充值」，支付宝或微信，有固定档位也可自定义。**先充 10–20 元就够试很久**；注意 API 与网页版是两套账，网页和 App 里免费对话不消耗这里的余额。
4. **创建密钥** —— 左侧「API keys」→「创建 API key」，起个以后认得出的名字。
5. **立刻复制保存** —— 密钥以 `sk-` 开头，**只在创建时完整显示一次**，关掉就看不到了，丢了只能重建。

**第二步：在 ZCode 里添加供应商**

入口：点对话框里的模型名 →「管理模型」→ 设置 → **模型设置** → 左侧供应商列表底部「添加供应商」。名称随便起（只是给自己的标签），「添加模型」那步要手动输入模型 ID，其余两项直接填：

| 字段 | 填什么 |
|------|--------|
| 名称 | `DeepSeek` |
| OpenAI 接口地址 | `https://api.deepseek.com/v1` |
| API Key | 刚复制的 `sk-...` |
| 模型 | `deepseek-flash`、`deepseek-v4-pro` |

保存后**打开启用开关**，回到对话框就能在模型列表里选到它。选它发一句最简单的指令（比如「列一下当前目录」）确认能跑通 —— **能出结果就说明地址、Key、模型名三样都对上了**，比逐项核对快。

**几个值得知道的点：**

- **协议不是单独的下拉框**，由你填哪个地址决定：填「OpenAI 接口地址」就走 OpenAI 协议，填「Anthropic 接口地址」（DeepSeek 这边是 `https://api.deepseek.com/anthropic`）就走 Anthropic 协议。**用充值余额的话选 OpenAI 那条** —— 官方文档对余额场景专门提醒过。
- **模型名以平台当前文档为准。** 上面两个名字来自 DeepSeek 官方文档的当前版本（`deepseek-flash` 对应 V4.1-Flash，`deepseek-v4-pro` 对应 V4-Pro），但模型会改名、会下线。顺手举证：ZCode 官方文档里那份 DeepSeek 示例写的还是 `deepseek-chat` 与 `deepseek-reasoner`，而这两个名字在 DeepSeek 现在的文档里已经查不到了。**填之前对一眼平台文档，别照抄任何二手示例** —— 包括这篇。
- **非峰值时段半价**：峰值是 UTC 周一至周五 01:00–04:00 与 06:00–10:00，其余时间按半价计费。
- 每个模型的「高级」里可以改最大输出 token 与上下文窗口（自定义供应商的模型才有），改动只对**新会话**生效。

## 四、配置放在哪里：两个作用域

如果这篇只记一张表，记这张。**用户级**在家目录、对所有项目生效；**工作区级**在仓库里、只对当前项目生效，可以随版本控制共享给协作者。

| 资源 | 用户级 | 工作区级 | 同名时谁生效 |
|------|--------|----------|--------------|
| **Skill** | `~/.zcode/skills/` | `<repo>/.zcode/skills/` | 用户级 |
| **Command** | `~/.zcode/commands/` | `<repo>/.zcode/commands/` | 用户级 |
| **MCP** | `~/.zcode/cli/config.json` 的 `mcp.servers` | `<repo>/.zcode/config.json` 的 `mcp.servers` | 用户级 |
| **Hook** | `~/.zcode/cli/config.json` 的 `hooks` | `<repo>/.zcode/config.json` 的 `hooks` | 用户级 |
| **Plugin** | 市场安装，启停状态在 `~/.zcode/cli/config.json` | — | 不适用 |
| **`AGENTS.md`** | `~/.zcode/AGENTS.md` | `<repo>/AGENTS.md` | 工作区级 |

表格之外几句：想跨项目复用就放用户级，想随仓库共享就放工作区级；想跨工具复用（Claude、Codex、Cursor 也认）用 `.agents/` 备用路径（`~/.agents/skills/`、`<repo>/.agents/commands/` 等），只在 ZCode 里覆盖同名 skill 才用 `.zcode/skills/`。MCP 与 Hook 两行给的是**文件位置**，真正要写的是「的」字后面那个字段。

两点容易反直觉：**MCP 同名时用户级胜出**，别以为仓库里的会盖住全局那份；`.agents/mcp.json` 只是兼容回退 —— 同一作用域内先读 `.zcode`，那边完全没有 MCP 才回退过去，而两者键名还不一样（`.zcode` 用嵌套的 `mcp.servers`，`.agents` 用顶层的 `mcpServers`）。另外**一个插件可以同时贡献** skill、command、hook、MCP 与 agent，它带来的 hook 自动入链。

改界面偏好（托盘行为、语言、窗口大小）在客户端里点就行，不用手改文件 —— 那些存在 `~/.zcode/v2/setting.json`，属于桌面客户端自己的状态，不在上表里。

## 五、AGENTS.md：最该先写的那份

上面五类都是「给它加能力」，而 `AGENTS.md` 是**告诉它规矩**：语言偏好、审查风格、架构边界、测试要求、提交规范。它会被直接注入模型上下文，所以是投入产出比最高的一份配置。

- 用户级 `~/.zcode/AGENTS.md` 放跨项目的个人偏好（「回答用中文」「改动前先跑测试」）；工作区级 `<repo>/AGENTS.md` 放该仓库特有的约束，随仓库共享。
- **合并顺序**：用户级先注入、工作区级后注入，后者能收窄或覆盖前者 —— 惯例是「宽泛偏好放用户级，项目规则放工作区级」。
- 工作区那份是从当前工作目录**向上查找至项目根**解析出来的。
- 内置 `/init` 作用于**当前工作区**的 `AGENTS.md`，不会去改用户级那份。

## 六、常见问题

**装不上、起不来**（macOS 提示「已损坏」／ Linux 上 AppImage 跑不起来／ Windows 被防火墙或杀毒拦截）——
前两个见第二节对应平台的命令（`xattr` 与 `chmod +x`，AppImage 还要确认 `fuse`）；Windows 被拦时临时关掉实时防护，或把安装目录加进白名单后重试。

**Windows 上点关闭，窗口却只是消失了** —— 从 v3.4.0 起关闭窗口默认**隐藏到托盘**而不是退出，这样定时任务与闲时任务还能继续跑。想真的退出，去「设置 → 常规 → 通知」关掉「关闭窗口时隐藏到托盘」。这个开关是 Windows 独有的，而且**升级后会重置为开启一次**，即使你之前关过。

**填了第三方 Key 却连不上** —— 按顺序排查：余额是否充足（API 与网页版是两套账）、Key 是否复制完整（末尾别带空格）、模型名在当前平台文档里是否还存在、协议与地址是否配对（用余额就走 OpenAI 那条）。别漏了代理配置，那是最容易忽略的一环。

## 七、下一步

1. **写一份工作区 `AGENTS.md`** —— 先让它跑几个小改动，把它犯的错记进去，这份文件会越用越顺手。
2. **装一两个插件** —— 插件是打包分发 skill / command / hook / MCP 的方式，比自己攒文件省事。
3. **需要接外部工具时再配 MCP** —— 不需要就别配，少一层就少一类排查。

参考：[官网](https://zcode.z.ai/cn) ｜ [安装](https://zcode.z.ai/cn/docs/install) ｜ [连接模型](https://zcode.z.ai/cn/docs/configuration) ｜ [Skill](https://zcode.z.ai/cn/docs/skill) ｜ [Command](https://zcode.z.ai/cn/docs/commands) ｜ [MCP](https://zcode.z.ai/cn/docs/mcp-services) ｜ [Hooks](https://zcode.z.ai/cn/docs/hooks) ｜ [Plugin](https://zcode.z.ai/cn/docs/plugin) ｜ [快捷键表](https://zcode.z.ai/cn/docs/keyboard-shortcuts) ｜ [DeepSeek 开放平台](https://platform.deepseek.com) ｜ [DeepSeek API 文档](https://api-docs.deepseek.com)