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

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

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

五分钟路径

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

1. 下载安装 —— 官网取对应平台的包，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 装好。

安装包从官网下载，文件名带版本号（如 ZCode-3.11.2-win-x64.exe），别照抄版本号，以官网当页为准。

二、安装

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

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

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

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

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 开放平台：

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

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

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

保存后打开启用开关，回到对话框就能在模型列表里选到它。选它发一句最简单的指令（比如「列一下当前目录」）确认能跑通 —— 能出结果就说明地址、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 与上下文窗口（自定义供应商的模型才有），改动只对新会话生效。

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

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

表格之外几句：想跨项目复用就放用户级，想随仓库共享就放工作区级；想跨工具复用（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 —— 不需要就别配，少一层就少一类排查。

参考：官网 ｜ 安装 ｜ 连接模型 ｜ Skill ｜ Command ｜ MCP ｜ Hooks ｜ Plugin ｜ 快捷键表 ｜ DeepSeek 开放平台 ｜ DeepSeek API 文档