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

想在自己电脑上跑起一个智能体，其实比想象中简单：装一个客户端、接上一个模型，然后就能用自然语言让它读写文件、跑命令、看结果。

ZCode 是智谱推出的智能体开发环境（ADE）—— 说白了就是把 Agent 嵌进编辑器和终端的工作台。

这篇分两半：前半是怎样把它装起来并接上模型，其中有一条第三方 API 的完整走法（用 DeepSeek 举例）；后半是配置该放在哪 —— 后者往往比安装更容易绕晕，因为 ZCode 的扩展资源有两个作用域、五种类型，还各带一套覆盖规则。

下面涉及版本号的地方以当前最新的 v3.11.2 为准。只想先跑起来的话，直接看下面的「五分钟路径」。

五分钟路径

不打算现在就配环境、只想先让它跑起来，照这五步走：

1. 下载安装 —— 从官网取下对应平台的安装包。Windows 记得右键 → 以管理员身份运行。
2. 启动 —— 首次启动设置页点「开始使用 ZCode」，数据迁移那一步跳过不管。
3. 选工作区 —— 随便挑一个手头项目的文件夹即可，以后再换不迟。
4. 连模型 —— 两条路选一条：
   • 连 BigModel（步数最少）—— 点左下角「连接使用」→「连接 BigModel」→ 完成账号登录 → 回到供应商列表打开启用开关。
   • 用 DeepSeek 的 API Key —— 先去 DeepSeek 开放平台拿一个 Key（需要先完成实名认证并充值），再到「设置 → 模型设置 → 添加供应商」填好地址、Key 和模型名。要填的具体几项见 3.2。
5. 验证 —— 在对话框发一句「列一下当前目录的文件」。有回复，就成了。

到这里已经能用了。接着正式配之前，顺手确认一件事：

• 代理（见第三节开头）—— 网络走代理的话必须手动填，留空不等于跟随系统。这是最容易让人误判成"账号有问题"的一处。

想认真配一遍（扩展资源、AGENTS.md、规则谁覆盖谁）再从第一节读起。

一、安装前先确认

支持的平台：

• 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 装好。

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

二、安装

Windows

下载 .exe 后右键安装包，选择「以管理员身份运行」，按向导走完，再从开始菜单或桌面快捷方式启动。ARM64 机器选 -win-arm64.exe。

这一步别省。 直接双击在部分环境下会因权限不足导致安装中断或组件写入失败，而这类失败常常发生在向导中途、看不出明确原因。一律用管理员身份运行；装完之后日常启动不需要管理员权限。

macOS

打开 .dmg，把 ZCode.app 拖进「应用程序」，然后从启动台启动。Apple Silicon 与 Intel 是分开的两个包，选错会跑不起来。

如果系统提示「ZCode 已损坏，无法打开」，那是 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 用官方账号连接

没配模型时，点左下角的「连接使用」会进到登录页，三种方式：

1. 连接 Z.ai —— 官方账号。
2. 连接 BigModel —— 国内账号，无需海外支付，国内用户走这条更顺。
3. 使用 API Key —— 自带 Key。

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

除了官方账号，也可以接别家的模型。ZCode 支持任何兼容 OpenAI 或 Anthropic 协议的服务 —— 自定义供应商本质上就是填一个地址、一个 Key、一串模型 ID。下面用 DeepSeek 走一遍完整流程。

第一步：在开放平台拿到 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 那条。 官方文档对余额/资源包场景专门提醒过：要使用通用的 OpenAI 地址，不要选 Anthropic 协议。
• 模型名以平台当前文档为准。 上面两个名字来自 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 自动入链，不需要开那个开关（开关只针对手写 hook，见第五节）。

如果只是想改界面偏好（托盘行为、语言、窗口大小之类），在客户端里点就行，不用手改文件 —— 那些存在 ~/.zcode/v2/setting.json，属于桌面客户端自己的状态，不是上面这张表里的扩展配置。

五、五类资源的具体形态

上一节的表回答了「放哪、谁压谁」，这一节补上表格装不下的细节。

Skill：把做法写成文件

一个目录加一个 SKILL.md，就是一份可被按需加载的能力说明。上面那张表只列了路径，真正的查找是按顺序来的，越靠前优先级越高：

1. 显式配置的根目录
2. 用户 ~/.zcode/skills（其次 ~/.agents/skills）
3. 工作区 .zcode/skills（从当前目录向上直到仓库根，每一级都算）
4. 工作区 .agents/skills
5. 已启用插件提供的根目录（最低）

同一层里 .zcode 先于 .agents；更深的工作目录优先于仓库根。这里有个容易让人困惑的地方：同名 skill 都会被扫描到，但只有顺序最前的那份真正被加载 —— 文件明明在那儿却没反应，通常就是被更高优先级的同名 skill 遮住了。

Command：/ 菜单里的东西

一个 .md 文件一条命令。唯一需要记的规则是命名：嵌套目录用冒号连接，review/code.md 对应 /review:code，而不是 /review/code。

MCP：接外部工具

有一条需要注意的行为变化：工作区级声明的 MCP 服务器现在也默认被信任、随会话自动连接（早先需要手动授权）。方便，但也意味着只打开你信任的工作区 —— 克隆别人的仓库后随手打开，对方仓库里的 MCP 配置会被自动挂上。

Hook：在固定时机插入动作

支持七个事件，就这七个，没有别的：

SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop。

最容易卡住的是上一节表里提到的那个开关。把它和插件的差别放在一起看就清楚了：插件带来的 hook 自动启用，配置文件里写的必须显式打开 hooks.enabled: true。所以「同一个 hook 在 A 处能用、抄到 B 处就不动」，多半就出在这里。

Plugin：把上面几样打包

在「设置 → 插件管理」的「已安装」与「发现」两个页签里管理。插件目录带一份 .zcode-plugin/plugin.json 清单（兼容 .claude-plugin/、.codex-plugin/ 两个旧名字），最小只需要一个符合 ^[a-z0-9][a-z0-9._-]{0,127}$ 的 name。

市场可以从 GitHub 仓库、Git 地址、本地目录或文件添加。另外内置插件只能停用、不能卸载。

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

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

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

七、常见问题

1. macOS 提示「已损坏，无法打开」

Gatekeeper 的隔离标记，用前面 xattr 那条命令清掉即可。

2. Windows 上被防火墙或杀毒软件拦截

安装或启动被拦时，临时关掉实时防护，或把安装目录加进白名单后重试。

3. Linux 上 AppImage 跑不起来

先确认已经 chmod +x；部分发行版还需要装 fuse。

4. Windows 上点关闭，窗口却只是消失了

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

5. 填了第三方 Key，却连不上

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

6. 改了配置但没反应

按第五节那份查找顺序逐个排查：是不是被更高优先级的同名资源遮蔽了？hook 是不是没开 hooks.enabled: true？MCP 同名时，是不是用户级那一份把工作区压掉了？

八、下一步

装好之后值得接着做的三件事：

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

参考：

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